[DOCS] Improve Backend layout documentation (#532)

* [DOCS] Improve Backend layout documentation In preparation for documenting TYPO3-Documentation/Changelog-To-Doc#922 Releases: main, 12.4 * Update Documentation/PageTsconfig/Mod/WebLayout/BackendLayout.rst
TYPO3-Documentation · Jun 23, 2024 · 725ad65 · 725ad65
1 parent 4d9b7a2
commit 725ad65
Show file tree

Hide file tree

Showing 5 changed files with 113 additions and 3 deletions.
diff --git a/Documentation/Images/ManualScreenshots/BackendLayouts/PageModule.png b/Documentation/Images/ManualScreenshots/BackendLayouts/PageModule.png
diff --git a/Documentation/Images/ManualScreenshots/BackendLayouts/PageProperties.png b/Documentation/Images/ManualScreenshots/BackendLayouts/PageProperties.png
diff --git a/Documentation/PageTsconfig/Mod/WebLayout.rst b/Documentation/PageTsconfig/Mod/WebLayout.rst
@@ -55,17 +55,22 @@ BackendLayouts
 ==============
 
 ..  confval:: BackendLayouts
-    :name: mod-web-layout-BackendLayouts
     :type: array
+    :no-index:
 
-    Allows to define backend layouts via Page TSconfig directly, without using database records.
+    Backend Layouts were initially introduced in order to customize the view of
+    the :guilabel:`Page` module in TYPO3 Backend for a page, but has then since grown also in
+    Frontend rendering to select for example Fluid template files via TypoScript for a page,
+    commonly used via :confval:`data:pagelayout <t3tsref:data-pagelayout>`.
+
+    See also the dedicated chapter :ref:`backend-layouts`.
 
 ..  _mod-web-layout-backendLayouts-example:
 
 Example: Define a backend layout
 --------------------------------
 
-..  literalinclude:: _backendLayouts-example.tsconfig
+..  literalinclude:: WebLayout/_backendLayouts-example.tsconfig
     :language: typoscript
     :caption: EXT:site_package/Configuration/page.tsconfig
 
@@ -316,3 +321,8 @@ Example: Define previews for custom content elements
         preview.table = EXT:site_mysite/Resources/Private/Templates/Preview/Table.html
         preview.list.tx_news = EXT:site_mysite/Resources/Private/Templates/Preview/TxNews.html
     }
+
+..  toctree::
+    :glob:
+
+    WebLayout/*
diff --git a/Documentation/PageTsconfig/Mod/WebLayout/BackendLayout.rst b/Documentation/PageTsconfig/Mod/WebLayout/BackendLayout.rst
@@ -0,0 +1,99 @@
+..  include:: /Includes.rst.txt
+
+..  _backend-layouts:
+
+===============
+Backend layouts
+===============
+
+Backend layouts were initially introduced in order to customize the view of
+the :guilabel:`Page` module in TYPO3 Backend for a page, but has then since grown also in
+Frontend rendering to select for example Fluid template files via TypoScript for a page,
+commonly used via :confval:`data:pagelayout <t3tsref:data-pagelayout>`.
+
+..  figure:: /Images/ManualScreenshots/BackendLayouts/PageModule.png
+
+    A page module with a backend layout that has 3 content areas.
+
+Backend layouts are organized in rows and columns. Content areas can span
+multiple rows and or columns. They cannot be nested. For nested layouts in the
+backend use an extension like :composer:`b13/container`.
+
+The page TSconfig for the backend layout above can be found in the site package
+tutorial: :ref:`Create the backend page layouts <t3sitepackage:backend-page-layouts>`.
+
+For extended examples have a look at the predefined `backend layouts of the bootstrap
+package (GitHub) <https://github.com/benjaminkott/bootstrap_package/tree/master/Configuration/TsConfig/Page/Mod/WebLayout/BackendLayouts>`__.
+
+..  confval-menu::
+
+..  confval:: BackendLayouts.[backendLayout]
+    :name: mod-web-layout-BackendLayouts
+    :type: array
+    :Path: mod.web_layout.BackendLayouts
+
+    ..  confval:: title
+        :name: mod-web-layout-BackendLayouts-backendLayout-title
+        :type: string or language identifier
+
+        The title of the backend layout. It will be displayed in the page
+        properties in the backend.
+
+        ..  figure:: /Images/ManualScreenshots/BackendLayouts/PageProperties.png
+            :caption: Choose the backend layout in the page properties
+
+    ..  confval:: icon
+        :name: mod-web-layout-BackendLayouts-backendLayout-icon
+        :type: string, extension path to an image file
+
+        The icon to be displayed in the page properties.
+
+        ..  code-block:: tsconfig
+            :caption: EXT:bootstrap_package/Configuration/TsConfig/Page/Mod/WebLayout/BackendLayouts/subnavigation_right_2_columns.tsconfig
+
+            mod.web_layout.BackendLayouts.subnavigation_right_2_columns {
+                icon = EXT:bootstrap_package/Resources/Public/Icons/BackendLayouts/subnavigation_right_2_columns.svg
+            }
+
+    ..  confval:: config.backend_layout
+
+        ..  confval:: colCount
+            :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout.colCount
+            :type: integer
+
+            Total number of columns in the backend layout.
+
+        ..  confval:: rowCount
+            :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout.rowCount
+            :type: integer
+
+            Total number of rows in the backend layout.
+
+        ..  confval:: rows.[row].columns.[col]
+
+            ..  confval:: name
+                :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout-rows-row-columns-col-name
+                :type: string or language identifier
+
+                Name of the input area where content elements can be added. Will be
+                displayed in the :guilabel:`Page` module.
+
+            ..  confval:: colPos
+                :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout-rows-row-columns-col-colPos
+                :type: integer, 0 - maxInt
+
+                When content elements are added to this area, the value of `colPos`
+
+            ..  confval:: colspan
+                :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout-rows-row-columns-col-colspan
+                :type: integer, 1 - :confval:`mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout.colCount`
+
+                Can be used if the content element area should span multiple
+                columns as for the "Jumbotron" example in the example above.
+
+            ..  confval:: rowspan
+                :name: mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout-rows-row-columns-col-rowspan
+                :type: integer, 1 - :confval:`mod-web-layout-BackendLayouts-backendLayout-title-config-backend_layout.rowCount`
+
+                Can be used if the content element area should span multiple
+                rows.
diff --git a/...nfig/Mod/_backendLayouts-example.tsconfig → ...ebLayout/_backendLayouts-example.tsconfig b/...nfig/Mod/_backendLayouts-example.tsconfig → ...ebLayout/_backendLayouts-example.tsconfig
@@ -22,6 +22,7 @@ mod.web_layout.BackendLayouts {
                                 name = Main
                                 colPos = 0
                                 colspan = 1
+                                identifier = main
                             }
                         }
                     }