Configuration Files

Templating manual

Edit this chapter on Github Jump to...

3.1.5 Provider Extension Configuration Files

FluidTYPO3 File contexts, Configuration

Fluid Powered TYPO3 and the TYPO3 core itself enables several ways of adding the TypoScript you need to configure your extension's templates. Which one you should use is completely up to you, but each has drawbacks and advantages which you should know.

By convention your TypoScript files should be located in EXT:myextensionkey/Configuration/TypoScript as a pair of setup.txt and constants.txt. You can add multiple subfolders and register each one individually, for example splitting your TypoScript into a basic configuration file and one or more optional files with extended configuration - a strategy used by many popular TYPO3 extensions. In such a setup you might have the basic configuration files in EXT:myextensionkey/Configuration/TypoScript and some extended settings in EXT:myextensionkey/Configuration/TypoScript/ExtendedSettings; configuring TYPO3 to allow each one to be included individually.

Options for including TypoScript

The following options are official recommendations of the Fluid Powered TYPO3 team - other ways are possible but we neither recommend nor document these.

Option 1: Standard static TypoScript

This approach requires you to manually include the configuration in your site's configuration. The standard way to do this is to select the template in the "Includes" tab when editing a "TypoScript template" record.

// ext_tables.php
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile($_EXTKEY, 'Configuration/TypoScript', 'My settings');

Pros:

  • Supports constants - ideal for site manager's ease of use.
  • Is optional - ideal for multi-domain sites using multiple template collections.

Cons:

  • Requires manual inclusion in order to work - for completely automated deployment, another option may be a better fit.

Option 2: Minimal always-included defaults, inline

Always includes the configuration, in order of extension loading.

// ext_localconf.php
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScript($_EXTKEY, 'setup', '
    plugin.tx_myextensionkey.view {
        templateRootPaths.10 = EXT:flux/Resources/Private/Templates/
        partialRootPaths.10 = EXT:flux/Resources/Private/Partials/
        layoutRootPaths.10 = EXT:flux/Resources/Private/Layouts/
    }
');

Pros:

  • Automatic inclusion - no need for manually including the settings in "TypoScript template" records.
  • Very efficient - performs a simple string concatenation.

Cons:

  • No constants support unless you use a corresponding addTypoScript($_EXTKEY, 'constants', '...'); block.
  • TypoScript settings reside inside a PHP context which is poor separation of concerns.
  • Only way to disable the included TypoScript is to unset it which is inefficient.

Option 3: Flux hook to add to static configuration

Automatically and always include configuration, but do so in a way which simulates manually included static TypoScript templates.

// ext_localconf.php
\FluidTYPO3\Flux\Core::addStaticTypoScript('EXT:myextensionkey/Configuration/TypoScript/');

Pros:

  • Automatic inclusion in all templates.
  • Clearly separates setup and constants and places each into dedicated files.
  • Simulates manually included static files (which loads after for example option 2 above, but before manually included settings).

Cons:

  • (Marginally) less efficient than the other ways.
  • Like option 2, the only way to disable such inclusions is to unset it after it has been set.
Jump to...