diff --git a/Documentation/Images/Settings/SitePackageSettings.png b/Documentation/Images/Settings/SitePackageSettings.png new file mode 100644 index 00000000..2c0b8e9e Binary files /dev/null and b/Documentation/Images/Settings/SitePackageSettings.png differ diff --git a/Documentation/SiteSets/Index.rst b/Documentation/SiteSets/Index.rst index 9fabe6ea..b6dedb29 100644 --- a/Documentation/SiteSets/Index.rst +++ b/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 ` 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 ` we already created a basic site set for your site package. In step :ref:`Include the site sets of fluid-styled-content as -dependency ` we included the dependencies -to the site sets of :composer:`typo3/cms-fluid-styled-content`. +dependency ` 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 `. 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 `__ 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 `_. diff --git a/Documentation/SiteSets/Settings/Index.rst b/Documentation/SiteSets/Settings/Index.rst new file mode 100644 index 00000000..ccdb2e1e --- /dev/null +++ b/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 `_: + +.. 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 `_. + +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 `_. + +.. seealso:: + * `Site settings definitions `_ + * `Configuring the site settings editor `_ + * `Site management: Trouble shooting `_ + +.. _usage-settings-fluid: + +Using setting entries in a Fluid template +========================================= + +The site settings are available as variable `{settings}` +(see :ref:`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: + +.. 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 `_ +objects, for example in +`custom content element templates `_ +or within `Custom Content Blocks `_. +You would have to supply them with a `Custom data processor `_. + +.. _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 `_. + +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 `_. diff --git a/Documentation/SiteSets/Settings/_setting_entry.yaml b/Documentation/SiteSets/Settings/_setting_entry.yaml new file mode 100644 index 00000000..3cf85a79 --- /dev/null +++ b/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