[TASK] Overhaul module chapter (#1167)

* [TASK] Overhaul module chapter * Use confvals instead of tables * Correct indentation * Give headlines to examples * Introduce a toc for the properties releases: main, 12.4, 11.5 * Apply suggestions from code review Co-authored-by: Chris Müller <[email protected]> --------- Co-authored-by: Chris Müller <[email protected]>
TYPO3-Documentation · Apr 4, 2024 · d32ff1b · d32ff1b
1 parent be77d4f
commit d32ff1b
Showing 1 changed file with 81 additions and 62 deletions.
diff --git a/Documentation/TopLevelObjects/Module.rst b/Documentation/TopLevelObjects/Module.rst
@@ -1,7 +1,7 @@
-.. include:: /Includes.rst.txt
-.. index:: Top-level objects; module
+..  include:: /Includes.rst.txt
+..  index:: Top-level objects; module
 
-.. _tlo-module:
+..  _tlo-module:
 
 ======
 module
@@ -18,6 +18,7 @@ settings should be done globally and not changed on a per-page basis.
 Therefore they are usually done in the file
 :ref:`EXT:my_extension/ext_typoscript_setup.typoscript <t3coreapi:ext_typoscript_setup_typoscript>`.
 
+..  _module-options:
 
 Options for simple backend modules
 ===================================
@@ -26,108 +27,126 @@ In simple backend modules extension authors can decide how to use this
 namespace. By convention settings should go in the subsection
 :typoscript:`settings`.
 
-.. code-block:: typoscript
-   :caption: EXT:my_extension/ext_typoscript_setup.typoscript
+..  code-block:: typoscript
+    :caption: EXT:my_extension/ext_typoscript_setup.typoscript
 
-   module.tx_myextension_somemodule {
-       settings {
-           enablesomething = 1
-       }
-   }
+    module.tx_myextension_somemodule {
+        settings {
+            enablesomething = 1
+        }
+    }
+
+..  _tlo-module-options-extbase:
 
 Options for Extbase backend modules
 ===================================
 
-Most configuration options that can be done for Extbase frontend plugins
-can also be done for Extbase backend modules.
+Most configuration options that can be done for :ref:`Extbase <t3coreapi:extbase>` frontend plugins
+can also be done for Extbase backend modules:
 
+..  contents::
+    :local:
 
-.. index:: module; view.templateRootPaths
-.. _tlo-module-properties-templaterootpaths:
+..  index:: module; view.templateRootPaths
+..  _tlo-module-properties-templaterootpaths:
 
 view.templateRootPaths
 ----------------------
 
-.. rst-class:: dl-parameters
+..  confval:: view.templateRootPaths.[array]
+    :name: module-view-templateRootPaths
+    :type: file path with :ref:`stdWrap <stdwrap>`
 
-view.templateRootPaths
-   :sep:`|` :aspect:`Data type:` array of file paths with :ref:`stdWrap <stdwrap>`
-   :sep:`|`
+    Used to define several paths for templates, which are executed in reverse
+    order (the paths are searched from bottom to top). The first folder where
+    the desired layout is found is immediately used. If the array keys are numeric, they
+    are first sorted and then executed in reverse order.
 
-   Used to define several paths for templates, which are executed in reverse
-   order (the paths are searched from bottom to top). The first folder where
-   the desired layout is found is immediately used. If the array keys are numeric, they
-   are first sorted and then executed in reverse order.
+..  _tlo-module-properties-templaterootpaths-example:
 
-   **Example:**
+Example: Set the template root paths
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. code-block:: typoscript
-      :caption: EXT:my_extension/ext_typoscript_setup.typoscript
+..  code-block:: typoscript
+    :caption: EXT:my_extension/ext_typoscript_setup.typoscript
 
-      module.tx_somebackend_module {
-         view {
+    module.tx_somebackend_module {
+        view {
             templateRootPaths {
-               100 = EXT:my_extension/Resources/Private/Templates/Backend
+                100 = EXT:my_extension/Resources/Private/Templates/Backend
             }
-         }
-      }
+        }
+    }
 
-.. index:: module; view.partialRootPaths
-.. _tlo-module-properties-partialRootPaths:
+..  index:: module; view.partialRootPaths
+..  _tlo-module-properties-partialRootPaths:
 
 view.partialRootPaths
 ----------------------
 
-.. rst-class:: dl-parameters
+..  confval:: view.partialRootPaths.[array]
+    :name: module-view-partialRootPaths
+    :type: file path with :ref:`stdWrap <stdwrap>`
+
+    Used to define several paths for partials, which will be executed in reverse
+    order. The first folder where the desired partial is found, is used. The
+    keys of the array define the order.
 
-view.partialRootPaths
-   :sep:`|` :aspect:`Data type:` array of file paths with :ref:`stdWrap <stdwrap>`
-   :sep:`|`
 
-   Used to define several paths for partials, which will be executed in reverse
-   order. The first folder where the desired partial is found, is used. The
-   keys of the array define the order.
-   **Example:**
+Example: Set the partial root paths
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. code-block:: typoscript
-      :caption: EXT:my_extension/ext_typoscript_setup.typoscript
+..  code-block:: typoscript
+    :caption: EXT:my_extension/ext_typoscript_setup.typoscript
 
-      module.tx_somebackend_module {
-          view {
-              partialRootPaths {
-                  100 = EXT:my_extension/Resources/Private/Partials/Backend
-              }
-          }
-      }
+    module.tx_somebackend_module {
+        view {
+            partialRootPaths {
+                100 = EXT:my_extension/Resources/Private/Partials/Backend
+            }
+        }
+    }
+
+
+..  index:: module; settings
+..  _tlo-module-properties-settings:
 
 settings
 --------
 
+..  confval:: settings
+    :name: module-settings
+    :type: array<string, mixed>
+
 Here resides all of the settings. These settings are
-available in the Controller of the backend module as the array variable
+available in the controller of the backend module as the array variable
 :php:`$this->settings`.
 
-Example:
+Example: Limit pagination in the backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Show 25 news records in the backend module of the news extension:
 
-.. code-block:: typoscript
+..  code-block:: typoscript
    :caption: EXT:my_extension/ext_typoscript_setup.typoscript
 
    module.tx_news {
       settings.list.paginate.itemsPerPage = 25
    }
 
+Example: Register YAML file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Register your EXT:form configuration for the backend via TypoScript.
+Register your :doc:`typo3/cms-form:Index` configuration for the backend via TypoScript.
 
-.. code-block:: typoscript
-   :caption: EXT:my_extension/ext_typoscript_setup.typoscript
+..  code-block:: typoscript
+    :caption: EXT:my_extension/ext_typoscript_setup.typoscript
 
-   module.tx_form {
-       settings {
-           yamlConfigurations {
-               100 = EXT:my_extension/Configuration/Form/CustomFormSetup.yaml
-           }
-       }
-   }
+    module.tx_form {
+        settings {
+            yamlConfigurations {
+                # Use the current timestamp as key to avoid accidental overwriting
+                1712163960 = EXT:my_extension/Configuration/Form/CustomFormSetup.yaml
+            }
+        }
+    }