Configuration values (confval)¶
The confval
directive can be used to document configuration values
in a structured way, independent of the programming language.
In a TYPO3 context, it can be used to document configuration values
stored in PHP arrays (TCA, global configuration variables),
TypoScript (TypoScript setup, TSconfig), XML (FlexForms, XLIFF) and
YAML (SiteConfiguration, EXT:form).
Using the confval
directive has several benefits:
The display is independent of the language of the configuration value – for example, unlike PHP domain.
The values appear automatically in the generated keyword index.
You can link directly to configuration values.
The content element presents the data and its attributes in a well-structured way.
Each configuration value name may only be used once. In large references with different contexts you can define individual configuration schemas for each context.
Define a configuration schema¶
The directive confval
is predefined and can not be configured.
To introduce a new configuration schema add the following section to
the manuals Documentation/Settings.cfg
:
[sphinx_object_types_to_add]
my-custom-directive = my-custom-directive // my-custom-directive // My Cool Configuration Value section
It is possible to define several configuration schemes by listing them each in
one line, for example in the TypoScript reference we have one configuration
scheme for each content object like TEXT
, COA
or FILE
:
[sphinx_object_types_to_add]
cobj-coa = cobj-coa // cobj-coa // Content object COA
cobj-file = cobj-file // cobj-file // Content object FILE
cobj-text = cobj-text // cobj-text // Content object TEXT
The can then be used to define configuration values for each TypoScript
content object type using the directive used in the first part of the definition
after the =
sign, for example:
- value¶
- Data type
string / stdWrap
Text, which you want to output.
.. cobj-text:: value
:Data type: string / string / stdWrap
Text, which you want to output.
You can link to the specific configuration value by second part of the
definition, the one after the first //
sign:
Example
Use the value
property of the TEXT
content element.
Wrap it by stdWrap
. Note that the stdWrap
property
works different from the one from the stdWrap
property of the
COA
content object...
Use the :cobj-text:`value` property of the :typoscript:`TEXT` content element.
Wrap it by :cobj-text:`stdWrap`. Note that the :cobj-text:`stdWrap` property
works different from the one from the :cobj-coa:`stdWrap` property of the
:typoscript:`COA` content object...
The third entry of the configuration is used as label in the automatic Index entries (genindex.rst):

Automatic entries on the page genindex.rst.¶
Examples¶
Required configuration value¶
- label¶
- Required
true
- Type
string or LLL reference
- Scope
Display
- Path
$GLOBALS > TCA > [table] > columns > [field]
The name of the field as shown in the form.
.. confval:: label
:Required: true
:type: string or LLL reference
:Scope: Display
:Path: $GLOBALS > TCA > [table] > columns > [field]
The name of the field as shown in the form.
Configuration value with default value¶
- fileCreateMask¶
- Type
text
- Default
0664
- Path
$GLOBALS > TYPO3_CONF_VARS > SYS
File mode mask for Unix file systems (when files are uploaded/created).
.. confval:: fileCreateMask
:type: text
:Default: 0664
:Path: $GLOBALS > TYPO3_CONF_VARS > SYS
File mode mask for Unix file systems (when files are uploaded/created).
Custom configuration schemas¶
TEXT
- stdWrap¶
- Data type
stdWrap
stdWrap properties in the
TEXT
content element
COA
- stdWrap¶
- Data type
stdWrap
stdWrap properties in the
COA
content element
- 1,2,3, ...¶
- Data type
conten object
Any content object to be displayed
FILE
A file can also be put in the property 1,2,3, ...
of a
COA
content object.
- file¶
- Data type
file
The file to be displayed
- stdWrap¶
- Data type
stdWrap
stdWrap properties in the
FILE
content element
:typoscript:`TEXT`
.. cobj-text:: stdWrap
:Data type: stdWrap
stdWrap properties in the :typoscript:`TEXT` content element
:typoscript:`COA`
.. cobj-coa:: stdWrap
:Data type: stdWrap
stdWrap properties in the :typoscript:`COA` content element
.. cobj-coa:: 1,2,3, ...
:Data type: conten object
Any content object to be displayed
:typoscript:`FILE`
A file can also be put in the property :cobj-coa:`1,2,3, ...` of a
:typoscript:`COA` content object.
.. cobj-file:: file
:Data type: file
The file to be displayed
.. cobj-file:: stdWrap
:Data type: stdWrap
stdWrap properties in the :typoscript:`FILE` content element