[TASK] Adjust menu chapter for site package builder (#331)

* [TASK] Adjust menu chapter for site package builder

Releases: main, 13.4

* [TASK] Add breadcrumb Menu

Releases: main, 13.4

Documentation/Index.rst

@@ -136,7 +136,7 @@ https://github.com/TYPO3-Documentation/site_package
     Assets/Index
     FluidTemplates/Index
     ContentMapping/Index
-    MainMenuCreation/Index
+    Menu/Index
     SiteSets/Index
     ContentElementRendering/Index
     ContentBlocks/Index

Documentation/Menu/Breadcrumb.rst

@@ -0,0 +1,60 @@
+:navigation-title: Breadcrumb
+.. include:: /Includes.rst.txt
+
+..  _breadcrumb:
+
+=========================================
+Breadcrumb / rootline navigation in TYPO3
+=========================================
+
+If you use a `Generated site package <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_
+it already contains a breadcrumb navigation on the subpages.
+
+To display a breadcrumb the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_
+can be used with the special type `Rootline <https://docs.typo3.org/permalink/t3tsref:hmenu-special-rootline>`_.
+
+..  _breadcrumb-typoscript:
+
+Breadcrumb TypoScript - the data processor
+==========================================
+
+..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript
+    :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript
+    :linenos:
+    :emphasize-lines: 6-8
+
+Line 4: Each data processor must have a unique id. We used 10 for the
+`page-content data processor <https://docs.typo3.org/permalink/t3sitepackage:page-content-data-processor>`_
+and 20 for the :ref:`Main menu <main-menu-creation>` therefore we now use 30.
+
+Line 6: We configure the menu to use the special type
+`Rootline <https://docs.typo3.org/permalink/t3tsref:hmenu-special-rootline>`_.
+
+Line 7: We use the property :ref:`special.range <t3tsref:confval-hmenu-rootline-special-range>`
+to define that the breadcrumb should start at the root level (0) of the site and
+include the level of the current page (-1).
+
+Line 8: As the default variable of the menu data processor `menu` is already in
+use for the main menu, we rename the variable to be used for the breadcrumb to
+`breadcrumb`.
+
+..  _breadcrumb-fluid:
+
+Breadcrumb navigation Fluid template
+====================================
+
+The special type `breadcrumb` delivers the items of the rootline as an array.
+Therefore we can use the `For ViewHelper <f:for> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-for>`_
+to loop through these elements:
+
+..  literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html
+    :caption: packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html
+    :linenos:
+
+
+Line 1, 5: The data of the breadcrumb navigation can be found in variable
+`{breadcrumb}`. We defined this in line 8 of the :ref:`TypoScript <breadcrumb-typoscript>`.
+
+Line 6: As all items in the breadcrumb navigation are in the rootline of the
+current page all are marked as `active`. We therefore check if the page of the
+entry to be displayed is the `current` page.

Documentation/MainMenuCreation/Index.rst → Documentation/Menu/Index.rst

@@ -1,44 +1,76 @@
+:navigation-title: Menus
 .. include:: /Includes.rst.txt
-.. _main-menu-creation:
 
-=========
-Main menu
-=========
+..  _menu:
 
-To display a main menu in our frontend output we need to provide the according
-data and define the view by providing templates for it.
+========================
+Rendering menus in TYPO3
+========================
 
-A data processor (see :ref:`dataProcessing <t3tsref:dataProcessing>`) can be
-used to provide the data for the menu to the template and a Fluid template
-partial do define the view of the menu.
+There are several strategies to display menus or other navigation elements like
+breadcrumbs and sitemaps in TYPO3.
 
 ..  contents::
 
-.. _add-menu-processor:
+..  toctree::
+    :glob:
+    :hidden:
+
+    *
+
+..  _menu-content-element:
+
+Menus as content elements
+=========================
+
+You can use a content element to display a menu. In the example data "Page 1"
+contains a menu of subpages and page "Sitemap" a sitemap content element.
+
+To adjust the templates of these content elements refer to chapter
+`Overriding the default templates of content elements <https://docs.typo3.org/permalink/t3sitepackage:content-element-rendering>`_.
+
+..  _menu-page-view:
+
+Menus within the page view
+==========================
 
-Use the data processor `menu`
-=============================
+A data processor (see also :ref:`dataProcessing <t3tsref:dataProcessing>`) can be
+used to provide the data for one or several menus.
 
-The :ref:`data processor 'menu' <t3tsref:MenuProcessor>` can be configured to
-provide the data of all pages in your current site to your page template.
+For menus usually the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_,
+which is provided by the TYPO3 Core, is used.
 
-We save the TypoScript configuration for the menu into file
-:file:`Configuration/Set/SitePackage/TypoScript/Navigation/menu.typoscript`:
+..  tip::
+    Some extensions like :composer:`b13/menus` offer performant menus for
+    large sites or like :composer:`georgringer/news` menus for special purposes.
+
+.. _main-menu-creation:
+.. _add-menu-processor:
+
+TypoScrip configuration of the main menu
+========================================
+
+We use TypoScript to configure these menus. The main menu is configured like this:
 
 ..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/menu.typoscript
     :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/menu.typoscript
 
-.. _fluid-implement-main-menu:
+This menu defines that the variable with the default name `menu` should contain
+the information about the complete page tree of the current page.
+
+System folders like the "Footer menu" from your example data, special page types
+and pages excluded from the navigation are excluded.
 
-Update the Fluid partial for the menu
-=====================================
+A complete reference of this menu can be found in the TypoScript Reference:
+`menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_.
 
-Until now we had static HTML in the file
-:file:`Resources/Private/PageView/Partials/Navigation/Menu.html`.
+.. _fluid-implement-main-menu:
 
-We created that file in section :ref:`create_partial_header`.
+Fluid partial of the main menu
+==============================
 
-Replace the static HTMl with Fluid:
+In :path:`packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Menu.html`
+you can find the partial that renders the main menu.
 
 A menu usually contains several menu entries. We use the
 :ref:`t3viewhelper:typo3fluid-fluid-for` to iterate over all menu entries
@@ -101,29 +133,27 @@ displayed in the :ref:`Fluid inline notation <t3coreapi:fluid-inline-notation>`.
 Preview the page and use the menu
 =================================
 
-The menu in the page should now function and allow you to navigate from page to
-page.
+Whenever you change TypoScript files or Fluid templates, flush all caches:
 
-Delete the frontend caches and preview the changes:
+..  code-block:: bash
 
-When previewing the site as it stands now, we can verify if everything is
-working as expected and if the menu is generated. Go to **WEB → View** and
-check, if the menu reflects the pages you created in the backend. Add one or
-two additional pages to the page tree and check to see if they appear in the preview.
+    ddev typo3 cache:flush
 
 ..  figure:: /Images/MainMenuCreation/CheckMainMenu.png
     :alt: Checking from the backend if the menu is generated as expected.
     :class: with-shadow
 
     Checking from the backend if the menu is generated as expected.
 
-If the menu does not change, you possibly need to flush the frontend caches,
-then reload the preview.
+.. _menu-types:
 
-..  figure:: /Images/AutomaticScreenshots/FlushFrontendCaches.png
-    :class: with-shadow
+Different menu types
+====================
 
-    Flush the frontend cache after changing template files
+We use the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_
+to demonstrate different menu types:
 
-The preview in the screenshot above shows the menu with three page links: "Page
-1", "Page 2" and "Page 3".
+*   A breadcrumb configured in
+    :file:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript`
+    and rendered in :file:`packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html`.
+*   A footer menu (example is still missing).