diff --git a/Documentation/DataProcessing/MenuProcessor/Browse.rst b/Documentation/DataProcessing/MenuProcessor/Browse.rst index a4cd6fb51..74b54a405 100644 --- a/Documentation/DataProcessing/MenuProcessor/Browse.rst +++ b/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 ` 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 ` - :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 ` with -:typoscript:`special = browse` to display links like the following: - -.. code-block:: html - :caption: Example HTML output - - - - -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 ` + :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. diff --git a/Documentation/DataProcessing/MenuProcessor/_code-snippets/_BrowseNavigation.html b/Documentation/DataProcessing/MenuProcessor/_code-snippets/_BrowseNavigation.html new file mode 100644 index 000000000..21371b181 --- /dev/null +++ b/Documentation/DataProcessing/MenuProcessor/_code-snippets/_BrowseNavigation.html @@ -0,0 +1,9 @@ + + <- {prevNavigation.0.title} + + + {nextNavigation.0.title} -> + + + {upNavigation.0.title} + diff --git a/Documentation/DataProcessing/MenuProcessor/_code-snippets/_RelPrevNextMenu.typoscript b/Documentation/DataProcessing/MenuProcessor/_code-snippets/_RelPrevNextMenu.typoscript deleted file mode 100644 index 33f328765..000000000 --- a/Documentation/DataProcessing/MenuProcessor/_code-snippets/_RelPrevNextMenu.typoscript +++ /dev/null @@ -1,26 +0,0 @@ -page { - headerData { - // https://developers.google.com/search/blog/2011/09/pagination-with-relnext-and-relprev - 10 = HMENU - 10 { - special = browse - special { - items = prev|next - items.prevnextToSection = 1 - excludeNoSearchPages = 1 - } - - 1 = TMENU - 1.NO { - allWrap = |*| - doNotLinkIt = 1 - stdWrap { - typolink { - parameter.data = field:uid - returnLast = url - } - } - } - } - } -} diff --git a/Documentation/Images/ManualScreenshots/FrontendOutput/Hmenu/ContentObjectsHmenuSpecialBrowse.png b/Documentation/Images/ManualScreenshots/FrontendOutput/Hmenu/ContentObjectsHmenuSpecialBrowse.png deleted file mode 100644 index 43f1572e2..000000000 Binary files a/Documentation/Images/ManualScreenshots/FrontendOutput/Hmenu/ContentObjectsHmenuSpecialBrowse.png and /dev/null differ