:navigation-title: Usage in Fluid

..  include:: /Includes.rst.txt
..  _settings-fluid:

=============================================
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 :guilabel:`Site Management > Settings` module in the backend
by administrators.

..  _settings-definitions-yaml-constants:

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 :file:`settings.definitions.yaml` in your site set.

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

..  figure:: /Images/Settings/SitePackageSettings.png
    :alt: 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
:file:`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 <https://get.typo3.org/sitepackage>`_:

..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/settings.definitions.yaml
    :caption: packages/my_site_package/Configuration/Sets/SitePackage/settings.definitions.yaml

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:

..  literalinclude:: _setting_entry.yaml
    :linenos:
    :caption: packages/my_site_package/Configuration/Sets/SitePackage/settings.definitions.yaml (excerpt)

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 <https://docs.typo3.org/permalink/t3coreapi: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 <https://docs.typo3.org/permalink/t3coreapi:site-settings-definition-properties>`_.

..  seealso::
    *   `Site settings definitions <https://docs.typo3.org/permalink/t3coreapi:site-settings-definition>`_
    *   `Configuring the site settings editor <https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings-editor-configuration>`_
    *   `Site management: Trouble shooting <https://docs.typo3.org/permalink/t3start:site-management-trouble>`_

..  _usage-settings-fluid:

Using setting entries in a Fluid template
=========================================

The site settings are available as variable `{settings}`
(see :ref:`settings <t3tsref:confval-pageview-data-settings>`) within the templates
of the page as we are using the `PAGEVIEW <https://docs.typo3.org/permalink/t3tsref:cobj-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:

..  literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Footer.html
    :caption: packages/my_site_package/Resources/Private/PageView/Partials/Footer.html

At the time of writing the settings are not available out-of-the-box in
templates configured by `FLUIDTEMPLATE <https://docs.typo3.org/permalink/t3tsref:cobj-template>`_
objects, for example in
`custom content element templates <https://docs.typo3.org/permalink/t3sitepackage:content-element-rendering>`_
or within `Custom Content Blocks <https://docs.typo3.org/permalink/t3sitepackage:content-blocks>`_.
You would have to supply them with a `Custom data processor <https://docs.typo3.org/permalink/t3tsref:customdataprocessors>`_.

..  _usage-settings-typoscript:

Using settings in TypoScript
============================

In both frontend TypoScript and backend TypoScript, also called TSconfig, the
settings can be used with the
`TypoScript constants syntax <https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-using-constants>`_.

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

..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
    :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript

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:

..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/footerMenu.typoscript
    :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/footerMenu.typoscript

It is also possible to use settings in TypoScript conditions:
`Check if a setting/constant is set to a certain value <https://docs.typo3.org/permalink/t3tsref:condition-examples-constant>`_.