Using and setting TSconfig

This chapter gives an overview where TSconfig is set, how it can be edited, and the load order of the different variants.

TSconfig can be used in page, it is then referred to as "Page TSconfig", or for backend users and backend user groups, in which case it is known as "User TSconfig".

While the objects, properties and conditions are different, the syntax of TSconfig is basically the same as it is for TypoScript in frontend TypoScript templates, except for constants, which are not available in TSconfig.

Page TSconfig

Entering data

There are two ways to attach Page TSconfig to any given page. When editing a page, move to the "Resources" tab. The first way is to include a TSconfig file provided by an extension. The second is to directly enter code in the "Page TSConfig" field.

TSconfig-related fields in the Resources tab of a page

Page TSconfig is inherited along the page tree. Consider the TSconfig from the above screenshot:

mod.web_list.hideTables = sys_template

It means that we want to fully hide the "sys_template" table on the page where we defined this TSconfig and all of its child pages.

Page TSconfig is thus very convenient to have separate branches of the page tree behave differently.

Verify the final configuration

The full Page TSconfig for any given page can be viewed using the WEB > Info module and choosing the "Page TSconfig" action.

Viewing Page TSconfig using the Info module

Overwriting and modifying values

Properties, which are set in Page TSconfig, are valid for the page, on which they are set, and for all pages hierarchically below. You can overwrite and modify them in the Page TSconfig of the same page or a subpage.

Page TSconfig itself can be overwritten by User TSconfig.

Important

It is not possible to modify Page TSconfig in User TSconfig. Page TSconfig can only be overwritten in User TSconfig.

Example:

  • Add in Page TSconfig
RTE.default.showButtons = bold
  • You get the value "bold".
  • Add later in Page TSconfig
RTE.default.showButtons := addToList(italic)
  • Finally you get the value "bold,italic".

Setting default Page TSconfig

Page TSconfig is designed to be individual for branches of the page tree. However it can be very handy to set global values that will be initialized from the root of the tree.

In extensions this is easily done by the extension API function, \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig(). In the ext_localconf.php file of your extension you can call it like this to set default configuration:

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig('
        RTE.default {
                showButtons = cut,copy,paste,fontstyle,fontsize,textcolor
                hideButtons = class,user,chMode
        }
');

There is a global TYPO3_CONF_VARS value called $GLOBALS['TYPO3_CONF_VARS']['BE']['defaultPageTSconfig']. The API function above adds content to that array. The array value itself however should not be changed or set directly within LocalConfiguration.php. Instead, it is good practice to use the above API method to add your default Page TSconfig for instance within your project extension that contains other local settings like templates, frontend TypoScript and so on.

Register static Page TSconfig files

Register PageTS config files in Configuration/TCA/Overrides/pages.php of any extension, which will be shown in the page properties (the same way as TypoScript static templates are included):

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::registerPageTSConfigFile(
   'extension_name',
   'Configuration/TSconfig/Page/myPageTSconfigFile.txt',
   'My special config'
);

Note

The included files from the pages in the rootline are included after the default page TSconfig and before the normal TSconfig from the pages in the rootline.

User TSconfig

Entering data

User TSconfig is entered in the "TSconfig" field of either BE users or BE user groups records. For both, this field is located in the "Options" tab.

The TSconfig field in the Options tab of a BE user

There is no way to view User TSconfig in the backend directly.

TSconfig defined at user-level is considered more relevant than TSconfig defined at group-level. Thus if the same property is defined both for a group the user belongs to and for the user itself, the value defined for the user will prevail.

If a user is member of several groups, the TSconfig from each group will simply be accumulated, identical properties from later groups taking precedence over definitions from earlier groups.

Verify the final configuration

The full User TSconfig of the currently logged in backend user can be viewed using the SYSTEM > Configuration module and choosing the "User TSconfig" action.

Viewing User TSconfig using the Configuration module

Overwriting and modifying values

Properties, which are set in the TSconfig field of a group, are valid for all users of that group.

Values, which are set in one group, can be overwritten and modified in the same or another group. If a user is member of multiple groups, the TSconfig settings are evaluated in the order, in which the groups are included in the user account: When you are editing the backend user, the selected groups are evaluated from top to bottom.

Example:

  • Add in User TSconfig
page.RTE.default.showButtons = bold
  • You get the value "bold".
  • Add later in User TSconfig
page.RTE.default.showButtons := addToList(italic)
  • You get the value "bold,italic".

Finally you can overwrite or modify settings from groups, of which your user is a member, in the User TSconfig field of that user himself.

Example:

Let's say the user is a member of a usergroup with this configuration

TCAdefaults.tt_content {
        hidden = 1
        header = Hello!
}

Then we set the following values in the TSconfig field of the user himself

TCAdefaults.tt_content.header = 234
options.clearCache.all = 1

This would override the default value of the header ("234") and add the clear cache option. The default value of the hidden field is not changed and simply inherited directly from the group.

Overriding Page TSconfig in User TSconfig

All properties from Page TSconfig can be overwritten in User TSconfig by prepending the property name with page.. When a Page TSconfig property is set in User TSconfig that way, no matter, if in the TSconfig field of a group or a user, it overwrites the value of the according Page TSconfig property.

To illustrate this feature let's say the Web > Info > Localization Overview has been disabled via Page TSconfig:

mod.web_info.menu.function {
   TYPO3\CMS\Info\Controller\TranslationStatusController = 0
}

If however we activate this configuration in the TSconfig of a certain backend user, that user would still be able to select this menu item because the value of his User TSconfig overrides the same value set in the Page TSconfig, just prefixed with page.:

page.mod.web_info.menu.function {
   TYPO3\CMS\Info\Controller\TranslationStatusController = 1
}

Important

It is not possible to reference the value of a property from Page TSconfig and to modify this value in User TSconfig! If you set a property in User TSconfig, which already had been set in Page TSconfig, then the value from Page TSconfig will be overwritten.

The result of the example below is not the value "bold,italic", but the value "italic".

# Enable the "bold" button in Page TSconfig (!)
RTE.default.showButtons = bold
# Try to additionally add the "italic" button in User TSconfig (!)
page.RTE.default.showButtons := addToList(italic)

Setting default User TSconfig

User TSconfig is designed to be individual for users or groups of users. However it can be very handy to set global values that will be initialized for all users.

In extensions this is easily done by the extension API function, \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserTSConfig(). In the ext_localconf.php file of your extension you can call it like this to set a default configuration.

/**
 * Adding the admin panel to users by default and forcing the display of the edit-icons
 */
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserTSConfig('
        admPanel {
                enable.edit = 1
                module.edit.forceNoPopup = 1
                module.edit.forceDisplayFieldIcons = 1
                module.edit.forceDisplayIcons = 0
                hide = 1
        }
        options.enableBookmarks = 1
');

There is a global TYPO3_CONF_VARS value called $GLOBALS['TYPO3_CONF_VARS']['BE']['defaultUserTSconfig']. The API function above adds content to that array. The array value itself however should not be changed or set directly within LocalConfiguration.php. Instead, it is good practice to use the above API method to add your default User TSconfig for instance within your project extension that contains other local settings like templates, frontend TypoScript and so on.

Conditions

It is possible to use TypoScript conditions in both User TSconfig and Page TSconfig, just as it is done in TypoScript for templates.

For a general discussion about TypoScript conditions, please refer to TypoScript Syntax Study of the core API document.

For a list of available conditions, please refer to the TypoScript Reference.

Examples

[treeLevel = 1]
TCEFORM.tt_content.section_frame.disabled = 1
[GLOBAL]

The above TSconfig will hide the "section_frame" field of content elements only on the first level of the page tree.

Differences to conditions in TypoScript templates

There are some slight differences between conditions in TSconfig and conditions in TypoScript templates, which must be taken into account:

  • Conditions "usergroup" and "loginUser" apply to BE groups and BE users – respectively – and not to FE groups and FE users, quite obviously.
  • In the "globalString" condition, key "TSFE:" will not work because the TSFE global object only exists in the FE context. The "LIT:" key will not work either as it is used to compare TypoScript constants, which are not available in the BE context.
  • Note that conditions such as "PIDupinRootline" or "treeLevel" will apply correctly to pages that are being created but are not yet saved.
  • You can use custom conditions, though. [BigCompanyName\TypoScriptLovePackage\MyCustomTypoScriptCondition = 7]

Furthermore the following condition is available only in TSconfig:

adminUser

Checks whether the current BE user has admin rights or not. Value is 1 if the user is an admin, 0 if he is not.

Syntax:

[adminUser = 0/1]

Example:

The following condition will apply only if the BE user is an admin.

[adminUser = 1]

PHP API

The PHP API to retrieve page and user TSconfig in a backend module is (nowadays) straight forward:

// Retrieve user TSconfig of currently logged in user
// Note its good practice to encapsulate the $GLOBALS['BE_USER'] access in a getter method that returns an instance
// of BackendUserAuthentication for IDE auto completion, until core provides a dependency injection solution
$userTsConfig = $GLOBALS['BE_USER']->getTSConfig();

// Retrieve page TSconfig of currently logged in user
$pageTsConfig = BackendUtility::getPagesTSconfig($currentPageId);

There is one method each, both just return the entire TSconfig array. All the heavy lifting and merging is done, for instance overrides of page TSconfig by user TSconfig are already applied if retrieving the page Tsconfig for a given page id.

Similar to other TypoScript related API methods, properties that contain sub properties return their sub properties using the property name with a trailing dot, while a single property is accessible by the property name itself. The example below gives more insight on this.

If accessing TSconfig arrays, the PHP null coalescence operator ?? is almost always useful: TSconfig options may or not be set, accessing not existing array keys in PHP would thus raise PHP notice level warnings. Combining the array access with a fallback using ?? helps accessing these optional array structures.

// Incoming (user) TSconfig:
// options.someToggle = 1
// options.somePartWithSubToggles = foo
// options.somePartWithSubToggles.aValue = bar

// Parsed array returned by getTSConfig(), note the dot if a property has sub keys:
// [
//     'options.' => [
//         'someToggle' => '1',
//         'somePartWithSubToggles' => 'foo',
//         'somePartWithSubToggles.' => [
//             'aValue' => 'bar',
//         ],
//     ],
// ],
$userTsConfig = $this->getBackendUser->getTSConfig():

// Typical call to retrieve a sanitized value:
$isToggleEnabled = (bool)($userTsConfig['options.']['someToggle'] ?? false);

// Retrieve a sub set, note the dot at the end:
$subArray = $userTsConfig['options.']['somePartWithSubToggles.'] ?? [];