Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

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.

Table of contents

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.

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

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]

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

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
label	string or LLL reference
fileCreateMask	text	0664
someSetting	string

..  confval-menu::
    :name: confval-group-1
    :display: table
    :type:
    :default:
    :exclude: confval-1, confval-2

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
confval-1	string
confval-2	string

confval-1

Type: string

Some Description

confval-2

Type: string
Default: 'Hello World'

Some Description

..  confval-menu::
    :name: confval-group-2
    :display: table
    :type:

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

        Some Description

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

        Some Description

Confval-menu directive API

The confval-menu directive has the following options:

:display:: table, list, tree: Different display forms, just try them out
:name:: A unique identifier for the confval menu for the "to top" button
: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.