How to use settings as variables in templates

Certain information is used in different parts of the templates over and over again like the uid of the data privacy page or the contact e-mail address.

You can keep central information in settings. They can then be adjusted as needed in the Site Management > Settings module in the backend by administrators.

Setting definition

Settings definitions are used to set values that can be used in the TypoScript setup throughout the project.

They are stored in the file settings.definitions.yaml in your site set.

The settings can be displayed and adjusted in module Site Management > Settings:

Screenshot of module "Site Management > Settings" with the settings of the example site package open — Administrators can view and adjust settings and save them here.

If administrators change settings here, they get saved to config/sites/my-site/settings.yaml so this path and file have to be writable for TYPO3. If the file is not writable for example when you have it under version control, administrators can als export the settings and download them.

Let us have a look at the example generated by the Site Package Builder:

        packages/my_site_package/Configuration/Sets/SitePackage/settings.definitions.yaml
    

categories:
  MySitePackage:
    label: 'My Site Package'
  MySitePackage.templates:
    label: 'Templates'
    parent: MySitePackage
  MySitePackage.layout:
    label: 'Layout'
    parent: MySitePackage

settings:
  MySitePackage.template_path:
    label: 'Page template path'
    category: MySitePackage.templates
    description: 'Path to the templates of the My Site Package.'
    type: string
    default: 'EXT:my_site_package/Resources/Private/Templates/'

  MySitePackage.logo:
    label: 'Logo'
    category: MySitePackage.layout
    description: 'Path to the logo of My Site Package.'
    type: string
    default: 'EXT:my_site_package/Resources/Public/Images/logo.svg'

  MySitePackage.logo-alt:
    label: 'Logo Alt text'
    category: MySitePackage.layout
    description: 'Alternative text of the logo for the visually impaired'
    type: string
    default: 'Logo'

  MySitePackage.favicon:
    label: 'Favicon'
    description: 'This icon is displayed in search engine results and in the browser tab'
    category: MySitePackage.layout
    type: string
    default: 'EXT:my_site_package/Resources/Public/Icons/favicon.ico'

Settings can be assigned to categories so that they are easier to find for administrators. These categories are defined in lines 1-12.

Let us now have a look at the definition of a setting entry in detail:

        packages/my_site_package/Configuration/Sets/SitePackage/settings.definitions.yaml (excerpt)
    

MySitePackage.footerMenuRoot:
  label: 'Footer menu root uid'
  description: 'The subpages of this page are displayed in the footer'
  category: MySitePackage.menus
  type: int
  default: 2

Line 1 defines the identifier of the settings. Identifiers are available globally within the complete project and installed extensions might define some. Use a unique prefix therefore. Here we use MySitePackage.. We used the same prefix for the categories. This is suggested but not mandatory in a site package.

Line 2-3 define labels to be displayed in the backend module.

Line 4 sets the category.

Line 5 sets the type. See all available types here: Site setting definition types.

Line 6 defines a default. If you define a default its type in YAML has to match the type defined in line 5.

All properties that can be defined for setting definitions can be found here: Site setting definition properties.

Using setting entries in a Fluid template

The site settings are available as variable {settings} (see settings) within the templates of the page as we are using the PAGEVIEW TypoScript object.

In the site package example we display the logo once in the header in large and once in the footer in smaller and use the settings to determine the path and alt text in both cases:

packages/my_site_package/Resources/Private/PageView/Partials/Footer.html

<div class="container">
    <footer class="d-flex flex-wrap justify-content-between align-items-center py-3 my-4 border-top">
        <div class="col-md-4 d-flex align-items-center">

            <f:link.page pageUid="{site.rootPageId}" class="mb-3 me-2 mb-md-0 text-body-secondary text-decoration-none lh-1">
                <f:image src="{settings.MySitePackage.logo}" alt="{settings.MySitePackage.logo-alt}" height="24" class="bi" />
            </f:link.page>
            <span class="mb-3 mb-md-0 text-body-secondary">&copy; <f:format.date format="Y">now</f:format.date> {site.configuration.websiteTitle}</span>
        </div>

        <f:render partial="Navigation/FooterMenu.html" arguments="{_all}"/>
    </footer>
</div>

At the time of writing the settings are not available out-of-the-box in templates configured by FLUIDTEMPLATE objects, for example in custom content element templates or within Custom Content Blocks. You would have to supply them with a Custom data processor.

Using settings in TypoScript

In both frontend TypoScript and backend TypoScript, also called TSconfig, the settings can be used with the TypoScript constants syntax.

In the site package example we use constants to configure the path to the favicon and templates (both of type string):

        packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
    

page = PAGE
page {
  10 = PAGEVIEW
  10 {
    paths {
      0 = EXT:my_site_package/Resources/Private/PageView/
      10 = {$MySitePackage.template_path}
    }

    dataProcessing {
      # makes content elements available as {content} in Fluid template
      10 = page-content
    }
  }
  shortcutIcon = {$MySitePackage.favicon}
}

And in the footer menu we use a setting of type int to set the root folder in which the pages for the footer menu are found:

It is also possible to use settings in TypoScript conditions: Check if a setting/constant is set to a certain value.