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.
  • 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.

Examples

Required configuration value

label
Type
string or LLL reference
Required

true

The name of the field as shown in the form.

..  confval:: label
    :name: some-unique-label
    :required: true
    :type: string or LLL reference

    The name of the field as shown in the form.
Copied!

Example: Configuration value with default value and custom parameter

fileCreateMask
Type
text
Default
0664
Path
$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']

File mode mask for Unix file systems (when files are uploaded/created).

..  confval:: fileCreateMask
    :name: some-unique-fileCreateMask
    :type: text
    :default: 0664
    :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`

    File mode mask for Unix file systems (when files are uploaded/created).
Copied!

Confval directive API

Each confval must have at least a title. If that title is not unique within the manual the confval must also have the :name: attribute, followed by a unique name. Names are case-insensitive and convert all special signs into a dash.

..  confval:: [title]
    :name: [unique-name]
Copied!

There are several reserved attributes:

:type:
The type of the configuration value.
:default:
The default value
:required:
Is the configuration value required.
:name:
The unique identifier, reserved internally by reStructuredText.
:class:
Reserved internally by reStructuredText.
noindex
Exclude from being able to be referenced and form indexes. Useful for confvals that should be repeatedly displayed in different locations.

All other attributes are output the way they are written:

someSetting
Type
string
Path
$GLOBALS['TYPO3_CONF_VARS']['SYS']['someSetting']
Some value
Lorem Ipsum

Lorem Ipsum Dolor sit

..  confval:: fileCreateMask
    :name: some-unique-someSetting
    :type: string
    :default: 0664
    :Path: :php:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['fileCreateMask']`

    Lorem Ipsum Dolor sit
Copied!

Confval menu

Confval entries can be listed in a special menu type, the confval-menu directive.

If you put the directive somewhere on the page it will list all confvals that can be found on that page:

Name Type Default
string or LLL reference
text 0664
string
..  confval-menu::
    :display: table
    :type:
    :default:
    :exclude: confval-1, confval-2
Copied!

If you use a confval menu together with nested confvals it will only list its child confvals. This is useful if you have several groups of confvals on the same page and want to list them in separate menus:

Name Type
string
string
confval-1
Type
string

Some Description

confval-2
Type
string
Default
'Hello World'

Some Description

..  confval-menu::
    :display: table
    :type:

    ..  confval:: confval-1
        :type: string

        Some Description

    ..  confval:: confval-2
        :type: int
        :default: 'Hello World'

        Some Description
Copied!

Confval-menu directive API

The confval-menu directive has the following options:

:display:
table, list, tree: Different display forms, just try them out
:name:
Reserved by reStructuredText
:class:
Reserved by reStructuredText
:exclude-noindex:
Exclude all confvals that have the option :noindex:.
:exclude:
Comma separated list of all identifiers / titles of convals to be excluded.

All other parameters can be used to trigger listing of the property of the exact same name.