Skip to content

Commit

Permalink
[Backport 13.4] [TASK] Use Browse menus with Data processors (#1498)
Browse files Browse the repository at this point in the history 
* [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]>
  • Loading branch information
@github-actions @linawolf
github-actions[bot] and linawolf authored Dec 27, 2024
1 parent d4690af commit ac07ee2
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 225 deletions.
301 changes: 102 additions & 199 deletions Documentation/DataProcessing/MenuProcessor/Browse.rst
View file
Original file line number Diff line number Diff line change
@@ -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
==========
Expand All @@ -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.
9 changes: 9 additions & 0 deletions Documentation/DataProcessing/MenuProcessor/_code-snippets/_BrowseNavigation.html
View file
Original file line number Diff line number Diff line change
@@ -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>
26 changes: 0 additions & 26 deletions Documentation/DataProcessing/MenuProcessor/_code-snippets/_RelPrevNextMenu.typoscript
View file

This file was deleted.

Binary file removed ...ges/ManualScreenshots/FrontendOutput/Hmenu/ContentObjectsHmenuSpecialBrowse.png
View file
Binary file not shown.

0 comments on commit ac07ee2

Please sign in to comment.