[Backport 13.4] [FEATURE] Explain menu rendering with data processors (#1420)

* [FEATURE] Explain menu rendering with data processors

Releases: main, 13.4, 12.4

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Stefan Frömken <froemken@gmail.com>

---------

Co-authored-by: lina.wolf <lwolf@w-commerce.de>
Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com>
Co-authored-by: Stefan Frömken <froemken@gmail.com>

Author: 3 people

Documentation/Guide/Menu/Index.rst

@@ -1,48 +1,38 @@
 ..  include:: /Includes.rst.txt
-
 ..  _guide-menu:
 
-=============
-Create a menu
-=============
+=============================
+Create a menu with TypoScript
+=============================
 
 Until now, we learned how the page *content* is rendered; however, the
 page *navigation* is missing.
 
-TYPO3 CMS offers a special menu object called
-:ref:`HMENU <cobj-hmenu>` ("H" stands for hierarchical) to easily build
-different kinds of menus.
-
-We want our menu to be built like a nested list:
-
-..  literalinclude:: _menu.html
-
-It is customary to declare new objects as sub-properties of the
-`lib` top-level object. We can give it any name that hasn't
-been assigned yet:
-
-..  literalinclude:: _lib.textmenu.typoscript
-
-The :ref:`HMENU <cobj-hmenu>` object allows us to create a diversity of menus.
-The main properties are numbers and correspond to the menu level.
+TYPO3 provides a special data processor, the :ref:`menu data processor <MenuProcessor>`
+to pass data to render a menu to the Fluid template.
 
-The :ref:`TMENU <tmenu>` object renders a menu level as
-text. A different
-rendering can be chosen for each menu level.
+Configure the data processor in TypoScript:
 
-On every menu level, we can configure various states for the single
-menu items – see :ref:`menu items <menu-common-properties>`,
-e.g. `NO` for "normal", `ACT` for "pages in the root line"
-(i.e. the current page, its parent, grandparent, and so forth) or
-`CUR` for "the current page".
+..  literalinclude:: _menu.typoscript
+    :caption: TypoScript Setup
 
-..  important::
+And render the menu in your Fluid template. You need at least a
+:ref:`Minimal site package (see site package tutorial) <t3sitepackage:minimal-design>`
+to keep your templates in its private resources folder, for example
+:path:`/packages/site_package/Resources/Private/Templates`:
 
-   Except for the normal state (`NO`), other states have to be activated
-   before they get displayed (i.e. `ACT = 1`).
+..  literalinclude:: _MenuTemplate.html
+    :caption: /packages/site_package/Resources/Private/Templates/Pages/Default.html
 
-Now that our menu is defined, we can use it with:
+Find more examples on how to configure and render menus with TypoScript and
+Fluid in chapter
+:ref:`Main menu of the Site Package Tutorial <t3sitepackage:main-menu-creation>`.
 
-..  code-block:: typoscript
+You can find more examples on how to output menus of different styles, including
+multi-level menus, breadcrumbs, language menus, and sitemaps in the chapter
+about the :ref:`menu data processor <MenuProcessor>`.
 
-    page.5 < lib.textmenu
+..  note::
+    Before data processors were introduced it was common to use the TypoScript
+    object :ref:`HMENU <t3tsref:cobj-hmenu>` to render a menu. It is still
+    possible doing so and you might see it in older examples.

Documentation/Guide/Menu/_MenuTemplate.html

@@ -0,0 +1,18 @@
+<header>
+    <ul class="navbar-nav">
+        <f:for each="{myMainMenu}" as="menuItem">
+            <li class="nav-item">
+                <a class="nav-link {f:if(condition: menuItem.active, then:'active')}"
+                   href="{menuItem.link}"
+                   target="{menuItem.target}"
+                   title="{menuItem.title}"
+                >
+                    {menuItem.title}
+                </a>
+            </li>
+        </f:for>
+    </ul>
+</header>
+<main>
+    <p>Hello World!</p>
+</main>

Documentation/Guide/Menu/_lib.textmenu.typoscript

@@ -0,0 +1,13 @@
+page = PAGE
+page {
+  10 = FLUIDTEMPLATE
+  10 {
+    templateName = Default
+    templateRootPaths.10 = EXT:site_package/Resources/Private/Templates/Pages/
+    # ...
+    dataProcessing {
+      10 = menu
+      10.as = myMainMenu
+    }
+  }
+}