Skip to content

Commit 7b4213b

Browse files
linawolflinawolf
authored
[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
1 parent 8aff4fe commit 7b4213b

File tree

3 files changed

+128
-38
lines changed

3 files changed

+128
-38
lines changed

‎Documentation/Index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ https://github.com/TYPO3-Documentation/site_package
136136
Assets/Index
137137
FluidTemplates/Index
138138
ContentMapping/Index
139-
MainMenuCreation/Index
139+
Menu/Index
140140
SiteSets/Index
141141
ContentElementRendering/Index
142142
ContentBlocks/Index

‎Documentation/Menu/Breadcrumb.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
:navigation-title: Breadcrumb
2+
.. include:: /Includes.rst.txt
3+
4+
.. _breadcrumb:
5+
6+
=========================================
7+
Breadcrumb / rootline navigation in TYPO3
8+
=========================================
9+
10+
If you use a `Generated site package <https://docs.typo3.org/permalink/t3sitepackage:minimal-design>`_
11+
it already contains a breadcrumb navigation on the subpages.
12+
13+
To display a breadcrumb the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_
14+
can be used with the special type `Rootline <https://docs.typo3.org/permalink/t3tsref:hmenu-special-rootline>`_.
15+
16+
.. _breadcrumb-typoscript:
17+
18+
Breadcrumb TypoScript - the data processor
19+
==========================================
20+
21+
.. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript
22+
:caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript
23+
:linenos:
24+
:emphasize-lines: 6-8
25+
26+
Line 4: Each data processor must have a unique id. We used 10 for the
27+
`page-content data processor <https://docs.typo3.org/permalink/t3sitepackage:page-content-data-processor>`_
28+
and 20 for the :ref:`Main menu <main-menu-creation>` therefore we now use 30.
29+
30+
Line 6: We configure the menu to use the special type
31+
`Rootline <https://docs.typo3.org/permalink/t3tsref:hmenu-special-rootline>`_.
32+
33+
Line 7: We use the property :ref:`special.range <t3tsref:confval-hmenu-rootline-special-range>`
34+
to define that the breadcrumb should start at the root level (0) of the site and
35+
include the level of the current page (-1).
36+
37+
Line 8: As the default variable of the menu data processor `menu` is already in
38+
use for the main menu, we rename the variable to be used for the breadcrumb to
39+
`breadcrumb`.
40+
41+
.. _breadcrumb-fluid:
42+
43+
Breadcrumb navigation Fluid template
44+
====================================
45+
46+
The special type `breadcrumb` delivers the items of the rootline as an array.
47+
Therefore we can use the `For ViewHelper <f:for> <https://docs.typo3.org/permalink/t3viewhelper:typo3fluid-fluid-for>`_
48+
to loop through these elements:
49+
50+
.. literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html
51+
:caption: packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html
52+
:linenos:
53+
54+
55+
Line 1, 5: The data of the breadcrumb navigation can be found in variable
56+
`{breadcrumb}`. We defined this in line 8 of the :ref:`TypoScript <breadcrumb-typoscript>`.
57+
58+
Line 6: As all items in the breadcrumb navigation are in the rootline of the
59+
current page all are marked as `active`. We therefore check if the page of the
60+
entry to be displayed is the `current` page.

Documentation/MainMenuCreation/Index.rst renamed to Documentation/Menu/Index.rst

Lines changed: 67 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,76 @@
1+
:navigation-title: Menus
12
.. include:: /Includes.rst.txt
2-
.. _main-menu-creation:
33

4-
=========
5-
Main menu
6-
=========
4+
.. _menu:
75

8-
To display a main menu in our frontend output we need to provide the according
9-
data and define the view by providing templates for it.
6+
========================
7+
Rendering menus in TYPO3
8+
========================
109

11-
A data processor (see :ref:`dataProcessing <t3tsref:dataProcessing>`) can be
12-
used to provide the data for the menu to the template and a Fluid template
13-
partial do define the view of the menu.
10+
There are several strategies to display menus or other navigation elements like
11+
breadcrumbs and sitemaps in TYPO3.
1412

1513
.. contents::
1614

17-
.. _add-menu-processor:
15+
.. toctree::
16+
:glob:
17+
:hidden:
18+
19+
*
20+
21+
.. _menu-content-element:
22+
23+
Menus as content elements
24+
=========================
25+
26+
You can use a content element to display a menu. In the example data "Page 1"
27+
contains a menu of subpages and page "Sitemap" a sitemap content element.
28+
29+
To adjust the templates of these content elements refer to chapter
30+
`Overriding the default templates of content elements <https://docs.typo3.org/permalink/t3sitepackage:content-element-rendering>`_.
31+
32+
.. _menu-page-view:
33+
34+
Menus within the page view
35+
==========================
1836

19-
Use the data processor `menu`
20-
=============================
37+
A data processor (see also :ref:`dataProcessing <t3tsref:dataProcessing>`) can be
38+
used to provide the data for one or several menus.
2139

22-
The :ref:`data processor 'menu' <t3tsref:MenuProcessor>` can be configured to
23-
provide the data of all pages in your current site to your page template.
40+
For menus usually the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_,
41+
which is provided by the TYPO3 Core, is used.
2442

25-
We save the TypoScript configuration for the menu into file
26-
:file:`Configuration/Set/SitePackage/TypoScript/Navigation/menu.typoscript`:
43+
.. tip::
44+
Some extensions like :composer:`b13/menus` offer performant menus for
45+
large sites or like :composer:`georgringer/news` menus for special purposes.
46+
47+
.. _main-menu-creation:
48+
.. _add-menu-processor:
49+
50+
TypoScrip configuration of the main menu
51+
========================================
52+
53+
We use TypoScript to configure these menus. The main menu is configured like this:
2754

2855
.. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/menu.typoscript
2956
:caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/menu.typoscript
3057

31-
.. _fluid-implement-main-menu:
58+
This menu defines that the variable with the default name `menu` should contain
59+
the information about the complete page tree of the current page.
60+
61+
System folders like the "Footer menu" from your example data, special page types
62+
and pages excluded from the navigation are excluded.
3263

33-
Update the Fluid partial for the menu
34-
=====================================
64+
A complete reference of this menu can be found in the TypoScript Reference:
65+
`menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_.
3566

36-
Until now we had static HTML in the file
37-
:file:`Resources/Private/PageView/Partials/Navigation/Menu.html`.
67+
.. _fluid-implement-main-menu:
3868

39-
We created that file in section :ref:`create_partial_header`.
69+
Fluid partial of the main menu
70+
==============================
4071

41-
Replace the static HTMl with Fluid:
72+
In :path:`packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Menu.html`
73+
you can find the partial that renders the main menu.
4274

4375
A menu usually contains several menu entries. We use the
4476
: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>`.
101133
Preview the page and use the menu
102134
=================================
103135

104-
The menu in the page should now function and allow you to navigate from page to
105-
page.
136+
Whenever you change TypoScript files or Fluid templates, flush all caches:
106137

107-
Delete the frontend caches and preview the changes:
138+
.. code-block:: bash
108139
109-
When previewing the site as it stands now, we can verify if everything is
110-
working as expected and if the menu is generated. Go to **WEB → View** and
111-
check, if the menu reflects the pages you created in the backend. Add one or
112-
two additional pages to the page tree and check to see if they appear in the preview.
140+
ddev typo3 cache:flush
113141
114142
.. figure:: /Images/MainMenuCreation/CheckMainMenu.png
115143
:alt: Checking from the backend if the menu is generated as expected.
116144
:class: with-shadow
117145

118146
Checking from the backend if the menu is generated as expected.
119147

120-
If the menu does not change, you possibly need to flush the frontend caches,
121-
then reload the preview.
148+
.. _menu-types:
122149

123-
.. figure:: /Images/AutomaticScreenshots/FlushFrontendCaches.png
124-
:class: with-shadow
150+
Different menu types
151+
====================
125152

126-
Flush the frontend cache after changing template files
153+
We use the `menu data processor <https://docs.typo3.org/permalink/t3tsref:menuprocessor>`_
154+
to demonstrate different menu types:
127155

128-
The preview in the screenshot above shows the menu with three page links: "Page
129-
1", "Page 2" and "Page 3".
156+
* A breadcrumb configured in
157+
:file:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/Navigation/breadcrumb.typoscript`
158+
and rendered in :file:`packages/my_site_package/Resources/Private/PageView/Partials/Navigation/Breadcrumb.html`.
159+
* A footer menu (example is still missing).

0 commit comments

Comments
 (0)