[FEATURE] Restructure conditions docs (#1573)

Improve headlines and structure, move examples to typoscript files or inline

Releases: main, 13.4, 12.4

Co-authored-by: lina.wolf <lwolf@w-commerce.de>

Author: github-actions[bot]

Documentation/CodeSnippets/TypoScriptSyntax/Conditions1.rst.txt

@@ -1,3 +1,5 @@
+:navigation-title: Conditions
+
 ..  include:: /Includes.rst.txt
 ..  index::
     Conditions
@@ -12,10 +14,9 @@
 ..  _condition-functions-in-all-contexts:
 ..  _condition-functions-in-frontend-context:
 
-
-==========
-Conditions
-==========
+=======================================
+Frontend TypoScript conditions criteria
+=======================================
 
 Frontend TypoScript conditions offer a way to conditionally change TypoScript
 based on current context. Do not confuse conditions with the

Documentation/CodeSnippets/TypoScriptSyntax/Conditions2.rst.txt

@@ -1,33 +1,26 @@
-.. include:: /Includes.rst.txt
-.. index::
-   TypoScript; Operator "["
-   TypoScript; Conditions
-   TypoScript; [GLOBAL] condition
-   TypoScript; Symfony expression language
-.. _typoscript-syntax-conditions:
-.. _typoscript-syntax-syntax-square-brackets:
-.. _typoscript-syntax-syntax-conditions:
-.. _typoscript-syntax-syntax-value:
-.. _typoscript-syntax-else-condition:
-.. _typoscript-syntax-end-condition:
-.. _typoscript-syntax-global-condition:
-.. _typoscript-syntax-conditions-expression-language:
-.. _typoscript-syntax-implementing-custom-conditions:
-
-
-==========
-Conditions
-==========
+:navigation-title: Conditions
+
+..  include:: /Includes.rst.txt
+..  index::
+    TypoScript; Operator "["
+    TypoScript; Conditions
+    TypoScript; [GLOBAL] condition
+    TypoScript; Symfony expression language
+..  _typoscript-syntax-conditions:
+..  _typoscript-syntax-implementing-custom-conditions:
+..  _typoscript-syntax-conditions-examples:
+
+===================================
+Conditions in the TypoScript syntax
+===================================
 
 TypoScript can contain :code:`if` and :code:`if / else` control structures. They
 are called `conditions`, their "body" is only considered if a condition criteria
 evaluates to true. Examples of condition criteria are:
 
--  Is a user logged in?
-
--  Is it Monday?
-
--  Is the page called in a certain language?
+-   Is a user logged in?
+-   Is it Monday?
+-   Is the page called in a certain language?
 
 Conditions are a TypoScript syntax construct. They are thus available in both
 frontend TypoScript and backend TSconfig. However, condition criteria are based
@@ -36,129 +29,164 @@ TypoScript and backend TSconfig. For example, the :typoscript:`frontend` variabl
 not exist in TSconfig, it is (obviously) impossible to have a backend TSconfig
 condition that checks for a logged in frontend user.
 
-For a reference of allowed condition criteria, please refer to the according
-chapter in the :ref:`frontend TypoScript Reference <conditions>` and
-the :ref:`backend TSconfig Reference <tsconfig-conditions>`. These references
-come with examples for single condition criteria as well.
+..  contents:: Table of contents
 
-The TSconfig and TypoScript backend modules show lists of existing conditions
-and allow simulating criteria verdicts to analyze their impact on the
-resulting TypoScript tree.
+..  _typoscript-syntax-conditions-usage:
 
-Condition criteria are based on
-the `Symfony expression language <https://symfony.com/doc/current/components/expression_language/syntax.html>`__.
-The Core allows extending the Symfony expression language with own variables and
-functions, see :ref:`symfony expression language API <t3coreapi:sel-within-typoscript-conditions>`
-for more details.
+Basic usage of TypoScript conditions
+====================================
 
+..  literalinclude:: _codesnippets/_basic.typoscript
+    :captions: packages/my_site_package/Configuration/TypoScript/setup.typoscript
 
-Basic example
-=============
+..  _typoscript-syntax-conditions-syntax:
+
+Syntax and rules
+================
 
-.. include:: /CodeSnippets/TypoScriptSyntax/Conditions1.rst.txt
+These general rules apply:
 
+..  _typoscript-syntax-conditions-confinements:
+..  _typoscript-syntax-conditions-braces:
+..  _typoscript-syntax-syntax-square-brackets:
+..  _typoscript-syntax-syntax-conditions:
 
-.. _typoscript-syntax-conditions-syntax:
+General condition syntax
+------------------------
 
-Syntax and rules
-================
+Conditions are encapsulated in :typoscript:`[` and :typoscript:`]`
 
-The general syntax is like this:
+..  _typoscript-syntax-the-global-condition:
+..  _typoscript-syntax-global-condition:
+..  _typoscript-syntax-else-condition:
+..  _typoscript-syntax-end-condition:
 
-.. include:: /CodeSnippets/TypoScriptSyntax/Conditions2.rst.txt
+`[GLOBAL]`, `[ELSE]` and `[END]`
+--------------------------------
 
-These general rules apply:
+:typoscript:`[ELSE]` negates a previous condition criteria and can contain
+a new body until :typoscript:`[END]` or :typoscript:`[GLOBAL]`. :typoscript:`[ELSE]`
+is considered if the condition criteria did *not* evaluate to true.
 
-* Conditions are encapsulated in :typoscript:`[` and :typoscript:`]`
+:typoscript:`[END]` and :typoscript:`[GLOBAL]` stop a given condition scope.
+This is similar to a closing curly brace :code:`}` in programming languages like PHP.
 
-* :typoscript:`[ELSE]` negates a previous condition criteria and can contain
-  a new body until :typoscript:`[END]` or :typoscript:`[GLOBAL]`. :typoscript:`[ELSE]`
-  is considered if the condition criteria did *not* evaluate to true.
+..  literalinclude:: _codesnippets/_condition.typoscript
+    :captions: packages/my_site_package/Configuration/TypoScript/setup.typoscript
 
-* :typoscript:`[END]` and :typoscript:`[GLOBAL]` stop a given condition scope.
-  This is similar to a closing curly brace :code:`}` in programming languages like PHP.
+Conditions automatically stop at the end of a text snippet (file or record), even
+without :typoscript:`[END]` or :typoscript:`[GLOBAL]`. Another snippet on the same
+level is in "global" scope automatically. The backend TypoScript and
+TSconfig modules may mumble about a not properly closed condition, though.
 
-* Multiple condition criteria can be combined using :typoscript:`or` or :typoscript:`||`,
-  as well as :typoscript:`and` or :typoscript:`&&`
+..  versionchanged:: 12.0
 
-* Single criteria can be negated using :typoscript:`!`
+    :typoscript:`[END]` and :typoscript:`[GLOBAL]` behave exactly the same. Both
+    are kept for historical reasons (for now).
 
-  .. versionchanged:: 12.0
+    Conditions automatically stop at the end of a text snippet (file or record).
 
-  :typoscript:`[END]` and :typoscript:`[GLOBAL]` behave exactly the same. Both
-  are kept for historical reasons (for now).
+..  _typoscript-syntax-end-condition-and:
+..  _typoscript-syntax-end-condition-or:
 
-* Conditions can use constants. They are available in frontend TypoScript "setup" and
-  in TSconfig from "site settings". A simple example if this constant
-  :typoscript:`myPageUid = 42` is set:
+Combining multiple TypoScript conditions with `and` or `or`
+-----------------------------------------------------------
 
-  .. code-block:: typoscript
+Multiple condition criteria can be combined using :typoscript:`or` or :typoscript:`||`,
+as well as :typoscript:`and` or :typoscript:`&&`
 
-      [traverse(page, "uid") == {$myPageUid}]
-          page.10.value = Page uid is 42
-      [end]
+..  literalinclude:: _codesnippets/_andor.typoscript
+    :captions: packages/my_site_package/Configuration/TypoScript/setup.typoscript
 
-* Conditions can *not* be nested within code blocks.
+Single criteria can be negated using :typoscript:`!`
 
-  .. versionchanged:: 12.0
+..  _typoscript-syntax-end-condition-constants:
 
-  Conditions *can* be nested into each other, if they are located in
-  different snippets (files or records), see example below. They can *not* be nested
-  within the same code snippet.
+TypoScript constant usage in Conditions
+---------------------------------------
 
-* A second condition that is *not* :typoscript:`[ELSE]`, :typoscript:`[END]`
-  or :typoscript:`[GLOBAL]` *stops* a previous condition and starts a new one.
-  This is the main reason conditions can *not* be nested within one text snippet.
+Conditions can use constants. They are available in frontend TypoScript "setup" and
+in TSconfig from "site settings". A simple example if this constant
+:typoscript:`myPageUid = 42` is set:
 
-* .. versionchanged:: 12.0
+..  code-block:: typoscript
 
-  :typoscript:`@import` *can* be nested
-  inside conditions. This allows conditional includes and is a new feature of the
-  TYPO3 v12 parser.
+    [traverse(page, "uid") == {$myPageUid}]
+        page.10.value = Page uid is 42
+    [end]
 
-* .. versionchanged:: 12.0
+..  _typoscript-syntax-end-condition-nesting:
 
-  Conditions automatically stop at the end of a text snippet (file or record), even
-  without :typoscript:`[END]` or :typoscript:`[GLOBAL]`. Another snippet on the same
-  level is in "global" scope automatically. The backend TypoScript and
-  TSconfig modules may mumble about a not properly closed condition, though.
+Nesting conditions via TypoScript imports
+-----------------------------------------
 
-* .. versionadded:: 12.1
+Conditions can *not* be nested within code blocks.
 
-  Using the null-safe operator is possible when accessing properties on objects
-  which might not be available in some context, for example `TSFE` in the
-  backend:
+..  code-block:: typoscript
 
-  .. code-block:: typoscript
+    # Invalid: Conditions must not be used within code blocks
+    # someIdentifier {
+    #    someProperty = foo
+    #    [frontend.user.isloggedIn]
+    #       someProperty = bar
+    #    [GLOBAL]
+    # }
 
-     # Previously
-     [getTSFE() && getTSFE().id == 123]
+..  versionchanged:: 12.0
 
-     # Now
-     [getTSFE()?.id == 123]
+Conditions *can* be nested into each other, if they are located in
+different snippets (files or records), see example below. They can *not* be nested
+within the same code snippet.
 
+A second condition that is *not* :typoscript:`[ELSE]`, :typoscript:`[END]`
+or :typoscript:`[GLOBAL]` *stops* a previous condition and starts a new one.
+This is the main reason conditions can *not* be nested within one text snippet.
 
-.. _typoscript-syntax-conditions-usage:
-.. _typoscript-syntax-conditions-combine:
-.. _typoscript-syntax-conditions-confinements:
-.. _typoscript-syntax-conditions-braces:
-.. _typoscript-syntax-the-global-condition:
-.. _typoscript-syntax-conditions-examples:
+:typoscript:`@import` *can* be nested
+inside conditions. This allows conditional includes and is a new feature of the
+TYPO3 v12 parser.
 
-Examples
-========
+..  _typoscript-syntax-end-condition-null-save:
 
-* If a user is logged in, or if the client is local, text will be
-  output in upper case:
+Using the null-safe operator in conditions
+------------------------------------------
 
-  .. include:: /CodeSnippets/TypoScriptSyntax/Conditions3.rst.txt
+..  versionadded:: 12.1
 
-* In case :code:`if` is empty and only a :code:`else` body is needed for a
-  single condition criteria, these two are identical:
+Using the null-safe operator is possible when accessing properties on objects
+which might not be available in some context, for example `TSFE` in the
+backend:
 
-  .. include:: /CodeSnippets/TypoScriptSyntax/Conditions4.rst.txt
+..  code-block:: typoscript
 
-* Conditions can *not* be nested within curly braces. The example below
-  is invalid syntax and the backend modules mumble with "missing braces":
+    # Previously
+    # [getTSFE() && getTSFE().id == 123]
 
-  .. include:: /CodeSnippets/TypoScriptSyntax/Conditions5.rst.txt
+    # Now
+    [getTSFE()?.id == 123]
+
+
+..  _typoscript-syntax-syntax-value:
+
+Allowed criteria in TypoScript conditions
+=========================================
+
+For a reference of allowed condition criteria, please refer to the according
+chapter in the :ref:`frontend TypoScript Reference <conditions>` and
+the :ref:`backend TSconfig Reference <tsconfig-conditions>`. These references
+come with examples for single condition criteria as well.
+
+The TSconfig and TypoScript backend modules show lists of existing conditions
+and allow simulating criteria verdicts to analyze their impact on the
+resulting TypoScript tree.
+
+..  _typoscript-syntax-conditions-expression-language:
+
+TypoScript conditions and the Symfony expression language
+=========================================================
+
+Condition criteria are based on
+the `Symfony expression language <https://symfony.com/doc/current/components/expression_language/syntax.html>`__.
+The Core allows extending the Symfony expression language with own variables and
+functions, see :ref:`symfony expression language API <t3coreapi:sel-within-typoscript-conditions>`
+for more details.