[TASK] Document using site settings

Documentation/SiteSets/Index.rst

@@ -1,9 +1,9 @@
 :navigation-title: Settings
-.. include:: /Includes.rst.txt
+..  include:: /Includes.rst.txt
 
-.. _extension-configuration:
-.. _ec-directory-structure:
-.. _site-sets-configuration:
+..  _extension-configuration:
+..  _ec-directory-structure:
+..  _site-sets-configuration:
 
 ============================================
 Site settings: Further configuration options
@@ -16,11 +16,16 @@ In step :ref:`Minimal site package - Create a basic site
 set <t3sitepackage:minimal-extension-siteset>` we created a basic site set for
 our site package.
 
-In step :ref:`content-mapping-site-set` we added dependencies to our site set.
 
-..  contents::
+..  contents:: Table of Contents
 
-.. _site_set:
+..  toctree::
+    :titlesonly:
+    :glob:
+
+    */Index
+
+..  _site_set:
 
 The site set
 ============
@@ -35,8 +40,8 @@ In step :ref:`Create a basic site set <t3sitepackage:minimal-extension-siteset>`
 we already created a basic site set for your site package.
 
 In step :ref:`Include the site sets of fluid-styled-content as
-dependency <t3sitepackage:content-mapping-site-set>` we included the dependencies
-to the site sets of :composer:`typo3/cms-fluid-styled-content`.
+dependency <t3sitepackage:content-mapping-site-set>` we included the
+dependencies to the site sets of :composer:`typo3/cms-fluid-styled-content`.
 
 Your site set configuration should now look like this:
 
@@ -50,9 +55,10 @@ provides one set, the name of the set should be the same as the
 :ref:`composer name <extension-configuration-composer>`.
 
 In line 4 and 5 dependencies are defined. In this example the site package
-depends on :composer:`typo3/cms-fluid-styled-content`, therefore the sets provided by this
-system extension are included as dependency. By doing so all settings
-and TypoScript definitions provided by the extension are automatically included.
+depends on :composer:`typo3/cms-fluid-styled-content`, therefore the sets
+provided by this system extension are included as dependency. By doing so all
+settings and TypoScript definitions provided by the extension are automatically
+included.
 
 Your site set folder now contains the following files:
 
@@ -66,7 +72,7 @@ Your site set folder now contains the following files:
         *   page.tsconfig
         *   setup.typoscript
 
-.. _site_settings:
+..  _site_settings:
 
 Introduce site settings to configure fluid-styled-content
 =========================================================
@@ -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/Settings/Index.rst

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

Documentation/SiteSets/Settings/_setting_entry.yaml

@@ -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