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 |
---|---|---|
|
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: |
|
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 |
---|---|---|
|
int |
Integer from 1 to 6, indicating at what heading level numbers should begin to be automatically inserted. For example, if set equal to 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
<chart:c1>[A10]{view: Pf.A10}
<ctl:>[]{default_chart_group: "foo"}
<chart:c2>[A20]{view: Pf.A20}
<chart:c3>[A30]{view: Pf.A30, group: "bar"}
<ctl:>[]{default_chart_group: "spam"}
<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