[TASK] Document using site settings

Releases: main, 13.4

Author: linawolf

Documentation/Images/Settings/SitePackageSettings.png

@@ -18,7 +18,13 @@ our site package.
 
 In step :ref:`content-mapping-site-set` we added dependencies to our site set.
 
-..  contents::
+..  contents:: Table of Contents
+
+..  toctree::
+    :titlesonly:
+    :glob:
+
+    */Index
 
 .. _site_set:
 
@@ -87,17 +93,5 @@ Here we override some values for maximal image width in text-media content
 elements, we enable a lightbox for images and set paths for overriding the
 templates of that extension.
 
-.. _settings-definitions-yaml-constants:
-
-Setting definition
-==================
-
-Settings definitions are used to set values that can be used in the TypoScript
-setup through out the project. Before they were kept in the file
-:file:`constants.typoscript`. Since TYPO3 v13 they can be stored in the file
-:file:`settings.definitions.yaml`. See
-`settings.definitions.yaml <https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-SitePackage-Code/blob/main/Configuration/Sets/SitePackage/settings.definitions.yaml>`__ in Github.
-
-It is best practice to use them for values that might
-want to be changed later on like paths, ids of important pages (contact,
-imprint, a system folder that contains certain records, ...).
+Settings can also be used in conditions:
+`Check if a setting/constant is set to a certain value <https://docs.typo3.org/permalink/t3tsref:condition-examples-constant>`_.

Documentation/SiteSets/Index.rst

@@ -0,0 +1,124 @@
+: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 through out 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
+    :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 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>`_.

Documentation/SiteSets/Settings/Index.rst

@@ -0,0 +1,6 @@
+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