[Backport 13.4] [TASK] Use Browse menus with Data processors (#1498)

* [TASK] Use Browse menus with Data processors

Remove HMENU usage and refer to older versions for that.

Releases: main, 13.4

* [TASK] Use Browse menus with Data processors

Remove HMENU usage and refer to older versions for that.

Releases: main, 13.4

---------

Co-authored-by: lina.wolf <[email protected]>

Author: github-actions[bot]

Documentation/DataProcessing/MenuProcessor/Browse.rst

@@ -1,23 +1,31 @@
 :navigation-title: Browse
 ..  include:: /Includes.rst.txt
 ..  _hmenu-special-browse:
+..  _MenuProcessor-special-browse:
 
-================================
-Browse - previous and next links
-================================
+===========================================
+Browse navigation - previous and next links
+===========================================
 
-This menu contains pages which give your user the possibility to
+This data processor provides pages which give your reader the possibility to
 browse to the previous page, to the next page, to a page with the
-table of contents and so on. The menu is built of items given by a
-list from the property ".items".
+table of contents and so on.
+
+..  tip::
+    In older TypoScript browser menus were created using the `HMENU` object.
+    This still works for backward compatibility reasons. We recommend to only use
+    data processors for newly created menus.
+
+    See :ref:`TYPO3 11, Browse navigation <t3tsref/:hmenu-special-browse>` for
+    examples how this was done.
 
 ..  attention::
-   Mount pages are *not* supported!
+    Mount pages are *not* supported!
 
 ..  contents::
-   :local:
+    :local:
 
-..  _hmenu-special-browse-properties:
+..  _MenuProcessor-special-browse-properties:
 
 Properties
 ==========
@@ -27,193 +35,88 @@ Properties
     :type:
     :Default:
 
-..  _hmenu-special-browse-value:
-
-..  confval:: special.value
-    :name: hmenu-browse-special-value
-    :type: integer /:ref:`stdWrap <stdwrap>`
-    :Default: current page ID
-
-    The default value can be overridden with a different page ID as starting
-    point for the menu in some rare use cases.
-
-
-..  _hmenu-special-browse-items:
-
-..  confval:: special.items
-    :name: hmenu-browse-special-items
-    :type: list of item names separated by `|`
-    :Default: Current page ID
-
-    Each element in the list (separated by `|`) is either a reserved item
-    name (see list) with a predefined function, or a user-defined name
-    which you can assign a link to any page. Note that the current page
-    cannot be the root-page of a site.
-
-    ..  rubric:: Reserved item names:
-
-    `next` / `prev`
-        Links to the next page / the previous page.
-        Next and previous pages are from the same "pid" as the current page id
-        (or "value") - that is the next item in a menu with the current page.
-        Also referred to as current level.
-
-        If :confval:`hmenu-browse-special-items-prevnextToSection` is set then
-        `next` / `prev` will link to the first
-        page of the next section / to the last page of the previous section,
-        too.
-
-    `nextsection` / `prevsection`
-        Links to the next section / the
-        previous section. A section is defined as the subpages of a page on
-        the same level as the parent (pid) page of the current page. Will not
-        work if the parent page of the current page is the root page of the
-        site.
-
-        ..  figure:: /Images/ManualScreenshots/FrontendOutput/Hmenu/ContentObjectsHmenuSpecialBrowse.png
-            :alt: Example for the usage of the property "items".
-
-    `nextsection_last` / `prevsection_last`
-        Where `nextsection` / `prevsection` links to the first page in a section, these
-        link to the last page. If there is only one page in the section that
-        will be both first and last. Will not work if the parent page of the
-        current page is the root page of the site.
-
-    `first` / `last`
-        First / last page on the current level. If
-        there is only one page on the current level that page will be both
-        first and last.
-
-    `up`
-        Links to the parent (pid) page of the current page (up 1
-        level). Will always be available.
-
-    `index`
-        Links to the parent of the parent page of the current
-        page(up 2 levels). May not be available, if that page is out of the
-        root line.
-
-
-..  _hmenu-special-browse-items-example:
-
-Example: Display different types of browse links
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If id = 20 is the current page then:
-
-21 = prev and first, 19 = next, 18 = last, 17 = up, 1 = index, 10 =
-nextsection, 11 = nextsection\_last
-
-prevsection and prevsection\_last are not present because id = 3 has
-no subpages!
-
-**TypoScript (only "browse"-part, needs also TMENU):**
-
-..  code-block:: typoscript
-    :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
-
-    xxx = HMENU
-    xxx.special = browse
-    xxx.special {
-        items = index|up|next|prev
-        items.prevnextToSection = 1
-        index.target = _blank
-        index.fields.title = INDEX
-        index.uid = 8
-    }
-
-..  _hmenu-special-browse-prevnexttosection:
-
-special.items.prevnextToSection
---------------------------------
-
-..  confval:: special.items.prevnextToSection
-    :name: hmenu-browse-special-items-prevnextToSection
-    :type: boolean
-    :Default: false
-
-    If set, the `prev` and `next` navigation will jump to the next section
-    when it reaches the end of pages in the current section. That way
-    `prev` and `next` will also link to the first page of the next section
-    / to the last page of the previous section.
-
-
-..  _hmenu-special-browse-target:
-
-special.[itemname].target
---------------------------
-
-..  confval:: special.[itemname].target
-    :name: hmenu-browse-special-itemname-target
-    :type: string
-
-    Optional or alternative target of the item.
-
-..  _hmenu-special-browse-uid:
-
-special.[itemname].uid
------------------------
-
-..  confval:: special.[itemname].uid
-    :name: hmenu-browse-special-itemname-uid
-    :type: integer (UID of page)
-
-    Optional or alternative page UID to link to.
-
-..  _hmenu-special-browse-fields:
-
-special.[itemname].fields.[field name]
----------------------------------------
-
-..  confval:: special.[itemname].fields.[field name]
-    :name: hmenu-browse-special-itemname-fields
-    :type: string
-
-    Use the provided string as linked text instead of the pages title.
-
-
-..  _hmenu-special-browse-fields-example:
-
-Example: Use "back" as text on the `prev` link
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This gives the link to the previous page the linked text "« back":
-
-..  code-block:: typoscript
-    :caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
-
-    prev.fields.title = « back
-
-
-..  _hmenu-special-browser-excludenosearchpages:
-
-special.excludeNoSearchPages
------------------------------
-
-
-..  confval:: special.excludeNoSearchPages
-    :name: hmenu-browse-special-excludeNoSearchPages
-    :type: boolean
-    :Default: false
-
-    If set, pages marked with the `no search` checkbox will be excluded from the menu.
-
-..  _hmenu-special-browser-example:
-
-Example: Pagination with rel="next" and rel="prev"
-==================================================
-
-The following snippet uses a :ref:`HMENU <cobj-hmenu>` with
-:typoscript:`special = browse` to display links like the following:
-
-..  code-block:: html
-   :caption: Example HTML output
-
-   <link rel="prev" href="http://www.example.org/page1" />
-   <link rel="next" href="http://www.example.org/page2" />
-
-The menu excludes pages with the flag :guilabel:`Include in Search` removed
-and jumps to the next section when the last of subpages is reached.
-
-..  literalinclude:: _code-snippets/_RelPrevNextMenu.typoscript
-    :caption: EXT:site_package/Configuration/TypoScript/Seo/Setup/RelPrevNextMenu.typoscript
+    ..  confval:: special.value
+        :name: hmenu-browse-special-value
+        :type: integer /:ref:`stdWrap <stdwrap>`
+        :Default: current page ID
+
+        The default value can be overridden with a different page ID as starting
+        point for the menu in some rare use cases.
+
+    ..  confval:: special.items
+        :name: hmenu-browse-special-items
+        :type: list of item names separated by `|`
+        :Required:
+
+        A list, separated by pipes `|`, containing the following item types:
+
+        `next` / `prev`
+            Links to the next page / the previous page.
+            Next and previous pages are from the same "pid" as the current page id
+            (or "value") - that is the next item in a menu with the current page.
+            Also referred to as current level.
+
+            If :confval:`hmenu-browse-special-items-prevnextToSection` is set then
+            `next` / `prev` will link to the first
+            page of the next section / to the last page of the previous section,
+            too.
+
+        `nextsection` / `prevsection`
+            Links to the next section / the
+            previous section. A section is defined as the subpages of a page on
+            the same level as the parent (pid) page of the current page. Will not
+            work if the parent page of the current page is the root page of the
+            site.
+
+        `nextsection_last` / `prevsection_last`
+            Where `nextsection` / `prevsection` links to the first page in a section, these
+            link to the last page. If there is only one page in the section that
+            will be both first and last. Will not work if the parent page of the
+            current page is the root page of the site.
+
+        `first` / `last`
+            First / last page on the current level. If
+            there is only one page on the current level that page will be both
+            first and last.
+
+        `up`
+            Links to the parent (pid) page of the current page (up 1
+            level). Will always be available.
+
+        `index`
+            Links to the parent of the parent page of the current
+            page(up 2 levels). May not be available, if that page is out of the
+            root line.
+
+    ..  confval:: special.items.prevnextToSection
+        :name: hmenu-browse-special-items-prevnextToSection
+        :type: boolean
+        :Default: false
+
+        If set, the `prev` and `next` navigation will jump to the next section
+        when it reaches the end of pages in the current section. That way
+        `prev` and `next` will also link to the first page of the next section
+        / to the last page of the previous section.
+
+    ..  confval:: special.excludeNoSearchPages
+        :name: hmenu-browse-special-excludeNoSearchPages
+        :type: boolean
+        :Default: false
+
+        If set, pages marked with the `no search` checkbox will be excluded from the menu.
+
+..  _MenuProcessor-special-browse-example:
+
+Example: Display a browse navigation
+====================================
+
+The menu data processor with `special = browse` returns the found items as an
+array. The items in this array contain no information about what kind of item
+(previous, next, up, etc) they are. We therefore recommend to only use one
+item kind per data processor:
+
+..  literalinclude:: _code-snippets/_BrowseNavigation.typoscript
+    :caption: config/sites/mySite/setup.typoscript
+
+The result of each data processor can then be used, assuming that the result is
+the first item of the array saved into the database.

Documentation/DataProcessing/MenuProcessor/_code-snippets/_BrowseNavigation.html

@@ -0,0 +1,9 @@
+<f:if condition="{prevNavigation.0}">
+    <a href="{prevNavigation.0.link}">&lt;- {prevNavigation.0.title}</a>
+</f:if>
+<f:if condition="{nextNavigation.0}">
+    <a href="{nextNavigation.0.link}">{nextNavigation.0.title} -&gt;</a>
+</f:if>
+<f:if condition="{upNavigation.0}">
+    <a href="{upNavigation.0.link}">{upNavigation.0.title}</a>
+</f:if>