Provide frontend TypoScript in a TYPO3 extension

Changed in version 13.1

TypoScript on a per-site basis can now be included via sites and sets.

Provide TypoScript in your extension or site package

TypoScript files must have the ending .typoscript.

They are located in Configuration/Sets/MySet within your extension. Read more about how to provide the TypoScript as set for TYPO3 v13 and above and how to provide TypoScript for both TYPO3 v13 and v12.

  • constants.typoscript contains the frontend TypoScript constants
  • setup.typoscript contains the frontend TypoScript

TypoScript provided as site set (only TYPO3 v13.1 and above)

The file structure of the extension could, for example look like this:

With the extension's TypoScript residing in EXT:my_extension/Configuration/Sets/MyExtension and the TypoScript for some optional feature in EXT:my_extension/Configuration/Sets/MyExtensionWithACoolFeature. Let us assume, that the optional feature depends on the main TypoScript.

The sets can now be defined for TYPO3 v13 as follows:

The main set of the extension

EXT:my_extension/Configuration/Sets/MyExtension/config.yaml
name: myvendor/my-extension
label: My Extension, main set
Copied!

The sub set for an optional feature

EXT:my_extension/Configuration/Sets/MyExtensionWithACoolFeature/config.yaml
name: myvendor/my-extension-with-a-cool-feature
label: Set for a cool feature

# This feature depends on the TypoScript and settings of the main set
dependencies:
  - myvendor/my-extension
Copied!

Overriding the TypoScript

The TypoScript provided in the site set will be loaded exactly once and respect the dependencies defined in the site set configuration. Therefore if you have to override the frontend TypoScript of another site set your site set should depend on the other site set:

packages/my_site_package/Configuration/Sets/MySitePackage/config.yaml
name: my-vendor/my-site-package
label: My Set
dependencies:
  - my-vendor/my-other-set
  - some-vendor/some-extension
Copied!

Your extension can then safely override frontend TypoScript of the some_extension, for example:

packages/my_site_package/Configuration/Sets/MySitePackage/setup.typoscript
plugin.some_extension_pi1.settings.someSetting = Special setting
Copied!

Supporting both site sets and TypoScript records

Changed in version 13.1

With TYPO3 13.1 site sets as TypoScript provider where introduced. Existing extensions should support site sets as well as TypoScript records for backward compatibility reasons.

One TypoScript include set

If your extension supported one static file include you should provide the same files in your main site set as well:

EXT:my_extension/Configuration/TCA/Overrides/sys_template.php (before and after)
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/',
    'Examples TypoScript'
);
Copied!

In your main site set provide the same files that where provided as includes by \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile until now:

  • packages/my_extension/Configuration/

    • Sets

      • MySet

        • config.yaml
        • constants.typoscript
        • setup.typoscript
    • TypoScript

      • constants.typoscript
      • setup.typoscript
packages/my_extension/Configuration/Sets/MySet/constants.typoscript
@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'
Copied!
packages/my_extension/Configuration/Sets/MySet/setup.typoscript
@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'
Copied!

Multiple TypoScript include sets

If there should be more then one set of TypoScript templates that may be included, they were usually stored in sub folders of Configuration/TypoScript until now.

When introducing site sets usually one site set per TypoScript record include set is needed:

  • packages/my_extension/Configuration

    • TypoScript

      • SpecialFeature1

        • constants.typoscript
        • setup.typoscript
      • SpecialFeature2

        • setup.typoscript
      • constants.typoscript
      • setup.typoscript
    • Sets

      • MyMainSet

        • config.yaml
        • constants.typoscript
        • setup.typoscript
      • MySpecialFeature1Set

        • config.yaml
        • constants.typoscript
        • setup.typoscript
      • MySpecialFeature2Set

        • config.yaml
        • setup.typoscript

For backward compability reasons ExtensionManagementUtility::addStaticFile still needs to be called for each folder that should be available in the TypoScript template record:

EXT:my_extension/Configuration/TCA/Overrides/sys_template.php
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/',
    'My Extension - Main TypoScript'
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/Example1/',
    'My Extension - Additional example 1'
);

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
    'my_extension',
    'Configuration/TypoScript/SpecialFeature2/',
    'My Extension - Some special feature'
);
Copied!

Each site set then provides the TypoScript files the according location by importing it, for example:

packages/my_extension/Configuration/Sets/MySet/setup.typoscript
@import 'EXT:my_extension/Configuration/TypoScript/MySpecialFeature2Set/setup.typoscript'
Copied!

Make TypoScript available (always load)

Use ExtensionManagementUtility::addTypoScript if the frontend TypoScript must be available in backend modules without page context, for example to register the YAML of the EXT:form system extension for the backend.

EXT:my_extension/ext_localconf.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTypoScript(
    'my_extension',
    'setup',
    '
        module.tx_form {
            settings {
                yamlConfigurations {
                    100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
                }
            }
        }
    ',
);
Copied!

More information