Skip to content

Commit

Permalink
[TASK] Overhaul HMENU browse page (#1178)
Browse files Browse the repository at this point in the history 
* Use confvals
* Correct indentation
* Overhaul example

releases: main, 12.4, 11.5

Co-authored-by: lina.wolf <[email protected]>
  • Loading branch information
@github-actions @linawolf
github-actions[bot] and linawolf authored Apr 3, 2024
1 parent fc2b510 commit c9aef7f
Showing 1 changed file with 130 additions and 161 deletions.
291 changes: 130 additions & 161 deletions Documentation/ContentObjects/Hmenu/Browse.rst
View file
Original file line number Diff line number Diff line change
@@ -1,244 +1,213 @@
.. include:: /Includes.rst.txt
.. index:: HMENU; special = browse
.. _hmenu-special-browse:
.. include:: /Includes.rst.txt
.. index:: HMENU; special = browse
.. _hmenu-special-browse:

=================================
================================
Browse - previous and next links
=================================
================================

This menu contains pages which give your user 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".

.. attention::
.. attention::
Mount pages are *not* supported!


.. contents::
.. contents::
:local:

.. _hmenu-special-browse-properties:

Properties
==========

.. _hmenu-special-browse-value:
.. _hmenu-special-browse-value:

special.value
--------------

.. ### BEGIN~OF~TABLE ###
.. container:: table-row

Property
special.value
.. confval:: special.value
:name: hmenu-browse-special-value
:type: integer /:ref:`stdWrap <stdwrap>`
:Default: current page ID

Data type
integer /:ref:`stdWrap <stdwrap>`
The default value can be overridden with a different page ID as starting
point for the menu in some rare use cases.

Default
current page id

Description
Default is the current page id. Seldom you might want to override this
value with another page-uid which will then act as the base point for
the menu and the predefined items.


.. _hmenu-special-browse-items:
.. _hmenu-special-browse-items:

special.items
---------------

.. container:: table-row

Property
special.items

Data type
list of item names separated by "\|"

Description
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.

*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 ".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
-------------

.. 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 pages. 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.
`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.
`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.
`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
rootline.
`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.

**Examples:**

If id = 20 is the current page then:
.. _hmenu-special-browse-items-example:

21 = prev and first, 19 = next, 18 = last, 17 = up, 1 = index, 10 =
nextsection, 11 = nextsection\_last
Example: Display different types of browse links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

prevsection and prevsection\_last are not present because id = 3 has
no subpages!
If id = 20 is the current page then:

**TypoScript (only "browse"-part, needs also TMENU):**
21 = prev and first, 19 = next, 18 = last, 17 = up, 1 = index, 10 =
nextsection, 11 = nextsection\_last

.. code-block:: typoscript
:caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
prevsection and prevsection\_last are not present because id = 3 has
no subpages!

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
}
**TypoScript (only "browse"-part, needs also TMENU):**

.. code-block:: typoscript
:caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
.. _hmenu-special-browse-prevnexttosection:
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
--------------------------------

.. container:: table-row

Property
special.items.prevnextToSection
.. confval:: special.items.prevnextToSection
:name: hmenu-browse-special-items-prevnextToSection
:type: boolean
:Default: false

Data type
boolean
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.

Description
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:
.. _hmenu-special-browse-target:

special.[itemname].target
--------------------------

.. container:: table-row

Property
special.[itemname].target
.. confval:: special.[itemname].target
:name: hmenu-browse-special-itemname-target
:type: string

Data type
string
Optional or alternative target of the item.

Description
Optional/alternative target of the item.

.. _hmenu-special-browse-uid:
.. _hmenu-special-browse-uid:

special.[itemname].uid
-----------------------

.. container:: table-row

Property
special.[itemname].uid

Data type
integer
.. confval:: special.[itemname].uid
:name: hmenu-browse-special-itemname-uid
:type: integer (UID of page)

Description
(uid of page) - optional/alternative page-uid to link to.
Optional or alternative page UID to link to.

.. _hmenu-special-browse-fields:
.. _hmenu-special-browse-fields:

special.[itemname].fields.[field name]
---------------------------------------

.. container:: table-row
.. confval:: special.[itemname].fields.[field name]
:name: hmenu-browse-special-itemname-fields
:type: string

Property
special.[itemname].fields.[field name]
Use the provided string as linked text instead of the pages title.

Data type
string

Description
Override field "field name" in pagerecord.
.. _hmenu-special-browse-fields-example:

**Example:**
Example: Use "back" as text on the `prev` link
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: typoscript
:caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
This gives the link to the previous page the linked text "« back":

prev.fields.title = « back
.. code-block:: typoscript
:caption: EXT:site_package/Configuration/TypoScript/setup.typoscript
This gives the link to the previous page the linktext "« back".
prev.fields.title = « back
.. _hmenu-special-browser-excludenosearchpages:
.. _hmenu-special-browser-excludenosearchpages:

special.excludeNoSearchPages
-----------------------------

.. container:: table-row

Property
special.excludeNoSearchPages

Data type
boolean

Default
0 (false)

Description
If set, pages marked with the "no search" checkbox will be excluded from the menu.


.. ###### END~OF~TABLE ######

[tsref:(cObject).HMENU.special = browse]
.. 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.

Example
=======
.. _hmenu-special-browser-example:

Pagination with rel="next" and rel="prev"
-----------------------------------------
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
.. code-block:: html
:caption: Example HTML output

<link rel="prev" href="http://www.example.org/page1" />
Expand All @@ -247,4 +216,4 @@ The following snippet uses a :ref:`HMENU <cobj-hmenu>` with
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.

.. include:: /CodeSnippets/Menu/TypoScript/RelPrevNextMenu.rst.txt
.. include:: /CodeSnippets/Menu/TypoScript/RelPrevNextMenu.rst.txt

0 comments on commit c9aef7f

Please sign in to comment.