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.

Note

This part is written for extension developers.

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:

Configuration
- Sets
  - MyExtension
  - MyExtensionWithACoolFeature
    - config.yaml
    - setup.typoscript
Resources
- ...
composer.json
...

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

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

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

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

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.

Warning

For historic reasons you might still see filenames like setup.ts and setup.txt. These files cannot be included with the @import syntax. All frontend TypoScript files must end on .typoscript.

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'
);

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'

packages/my_extension/Configuration/Sets/MySet/setup.typoscript

@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'

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'
);

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'

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
                }
            }
        }
    ',
);

Warning

While the content from the files ext_typoscript_setup.typoscript and ext_typoscript_constants.typoscript is loaded by default in sites based on TypoScript records it is not loaded in sites depending on site sets as TypoScript providers.

More information

TypoScript imports (in "Sitepackage Tutorial")`
Site settings: Further configuration options (in "Sitepackage Tutorial")`