Control Widgets#

A control widget does not produce any visible content in the page; instead, its job is to allow you to make settings that control how other widgets work, or how the page renders.

Format#

  • TYPE: ctl

  • NAME: Optional.

  • LABEL: Not accepted.

  • ROLE_FIELD: None.

  • CONTENT_FIELD: None.

Fields#

Required#

None.

Optional#

Field

Type

Description

default_WIDGETTYPE_FIELDNAME

any

Set default values for certain fields, for other widget types.

This actually represents a collection of fields, obtained by substituting a widget type, and a field name. For example: default_chart_group or default_doc_doc. See Setting defaults, below.

sectionNumbers

object

Controls automatic generation of section numbers in annotations (not supported in Sphinx pages). See sectionNumbers fields below.

Note

Generally, for all widget types, data field names use camelCase. However, the ctl widget fields of the form default_WIDGETTYPE_FIELDNAME are a special kind of “meta” field, in that their whole job is to set the value of other fields. Here, snake_case is employed because these field names have to include other field names within them, and those other names may already use camel case.

sectionNumbers fields#

The value of the control widget’s sectionNumbers field is an object. All fields within this object are optional, and are as defined in the table below.

At present, only one field is supported.

Field

Type

Description

topLevel

int

Integer from 1 to 6, indicating at what heading level numbers should begin to be automatically inserted.

For example, if set equal to 2, then the largest headings (given by # Heading in Markdown) will not have numbers, but all smaller headings will.

Default: 1

Setting defaults#

You can use control widgets to set the default values of certain DATA fields, for other widget types. You do this by defining a field whose name is of the form,

default_WIDGETTYPE_FIELDNAME

and where WIDGETTYPE and FIELDNAME are replaced with the type of the widget, and the name of its field, for which you want to set the default value.

For example, use the field name default_chart_group to set the default value of the group field for chart widgets.

Settings made in this way hold only within the page in which the control widget appears. They apply only to widgets coming after the control widget, and up until another control widget (if any) should set a different value.

For example, consider a page defined like this:

.. pfsc-chart:: c1: A10
    :view: Pf.A10

.. pfsc-ctl::
    :default_chart_group: "foo"

.. pfsc-chart:: c2: A20
    :view: Pf.A20

.. pfsc-chart:: c3: A30
    :view: Pf.A30
    :group: "bar"

.. pfsc-ctl::
    :default_chart_group: "spam"

.. pfsc-chart:: c4: A40
    :view: Pf.A40

Here, the value of the group field for chart widgets c1, c2, c3, and c4 would be, respectively, '' (the empty string), foo, bar, and spam.

Supported fields#

At this time, only the following default fields can be set:

  • default_chart_group

  • default_doc_group

  • default_doc_doc

Control and the substitution format#

We have indicated that a default setting made by a control widget applies only to widgets coming after it. But, when using the Substitution format in a Sphinx page, there are two parts: the inline reference, and the block definition. So, which part has to come after the control widget?

The answer is that it only matters where the definition appears, not the reference.

For example, consider the following page, whose author has misunderstood the rule.

Let's look at |the proof of Theorem 1|.

.. pfsc-ctl::
    :default_chart_group: "Thm2"

Meanwhile, let's also compare this to |the proof of Theorem 2|.

.. |the proof of Theorem 1| pfsc-chart::
    :view: Thm1.Pf

.. |the proof of Theorem 2| pfsc-chart::
    :view: Thm2.Pf

Here, because the reference |the proof of Theorem 1| comes before the control widget, you might imagine that the default group setting of "Thm2" was going to apply only to the second chart widget, not the first, but in fact this would be mistaken. Because the definition parts of both chart widgets on this page come after the control widget, its setting applies to both of them.

To put only the second chart widget (and others to come after it) into the "Thm2" group, the control widget can be moved down, like this:

Let's look at |the proof of Theorem 1|.

Meanwhile, let's also compare this to |the proof of Theorem 2|.

.. |the proof of Theorem 1| pfsc-chart::
    :view: Thm1.Pf

.. pfsc-ctl::
    :default_chart_group: "Thm2"

.. |the proof of Theorem 2| pfsc-chart::
    :view: Thm2.Pf