MenuGroup
The MenuGroup function can be used to output menu levels on the same level in a group.
Example: Members of a menu group
Unlike page groups, menu groups do not have to be separately defined. The members of the menu groups and their order result from the menu entries in the Site Store.
Starting from a page reference the menu levels (of the page reference) and their siblings are contained in the menu group (see example: all menu group members of the page reference new have a grey background).
Unlike the navigation, there is no query for menu groups whether a folder has been hidden from the navigation or not. Therefore, all folders of the menu group are always displayed, regardless of whether the checkbox Display in navigation menu? was selected in the Site Store or not!
In order for structured navigation to be possible within the pages, navigation elements must be integrated on all pages which belong to the menu group. To date the following elements have been supported:
- page forward (previousAvailable/previousNotAvailable)
- page back (nextAvailable/nextNotAvailable)
- Go to the first element (firstAvailable/firstNotAvailable)
- Go to the last element (lastAvailable/lastNotAvailable)
Furthermore, it is possible to generate a table of contents for the whole menu group, whereby the current element can be displayed differently to the other elements (delimiter/directoryRendering/directoryRenderingSelected).
Syntax of the MenuGroup function
The basic structure of the MenuGroup function is as follows:
<CMS_FUNCTION name="MenuGroup" resultname="IDENTIFIER">
<CMS_PARAM name="cycle" value="BOOLEAN_VALUE" />
<CMS_CDATA_PARAM name="delimiter"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="directoryRendering"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="directoryRenderingSelected"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="firstAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="firstNotAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="lastAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="lastNotAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="nextAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="nextNotAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="previousAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="previousNotAvailable"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>
MenuGroup function parameters
The MenuGroup function can be specified with the following parameters:
- cycle
- delimiter
- directoryRendering
- directoryRenderingSelected
- firstAvailable
- firstNotAvailable
- lastAvailable
- lastNotAvailable
- nextAvailable
- nextNotAvailable
- previousAvailable
- previousNotAvailable
All parameters are optional. |
The values of the individual parameters can be given as constants (<CMS_PARAM>), expressions (<CMS_VALUE_PARAM>) or template fragments (<CMS_CDATA_PARAM>). The parameter options are listed in the following table.
X means: can be used and recommended;
O means: use possible but not recommended;
- means: Use not possible
Parameter | Meaning | Specifying a constant | Specifying expressions | Specifying a template | Mandatory |
---|---|---|---|---|---|
cycle | Cyclical menu group | X | X | - | no |
delimiter | Fragment for | - | - | X | no |
directoryRendering | Fragment for | - | - | X | no |
directoryRenderingSelected | Fragment for the | - | - | X | no |
firstAvailable | Fragment for the first menu level of the menu group, if available. | - | - | X | no |
firstNotAvailable | Fragment for the first menu level of the menu group, if not available. | - | - | X | no |
lastAvailable | Fragment for the last menu level of the menu group, if available. | - | - | X | no |
lastNotAvailable | Fragment for the last menu level of the menu group, if not available. | - | - | X | no |
nextAvailable | Fragment for the next menu level of the menu group, if available. | - | - | X | no |
nextNotAvailable | Fragment for the next menu level of the menu group, if not available. | - | - | X | no |
previousAvailable | Fragment for the previous menu level of the menu group, if available. | - | - | X | no |
previousNotAvailable | Fragment for the previous menu level of the menu group, if not available. | - | - | X | no |
cycle parameter
As a default a menu group begins with the first menu level contained and ends with the last (cycle: 0).
If the cycle parameter is specified with value 1, the menu group becomes an endless sequence of menu levels (cyclical menu group), i.e. the last menu level is located in front of the first menu level and the first is after the last.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
<CMS_PARAM name="cycle" value="1" />
...
</CMS_FUNCTION>
delimiter / directoryRendering / directoryRenderingSelected parameters
When invoking the method $CMS_VALUE(VARNAME.directory)$ all menu levels of the menu group are output as a table of contents.
Decisive for display of the individual menu levels are the parameters: directoryRendering (inactive menu level) and directoryRenderingSelected (active/selected menu level). To separate the output of the individual menu levels, the delimiter parameter can be used to define a template fragment. This fragment, apart from in front of the first menu level and after the last menu level, is also output between two directoryRendering / directoryRenderingSelected outputs.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
...
<CMS_CDATA_PARAM name="delimiter"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="directoryRendering"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="directoryRenderingSelected"><![CDATA[...]]></CMS_CDATA_PARAM>
...
</CMS_FUNCTION>
firstAvailable / firstNotAvailable parameters
When using the invocation $CMS_VALUE(IDENTIFIER.first)$ (if the menu group contains at least one menu level) the first menu level is output as the template fragment specified with the firstAvailable parameter.
If the menu group is empty output is according to the template fragment specified with the firstNotAvailable parameter.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
...
<CMS_CDATA_PARAM name="firstAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="firstNotAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
...
</CMS_FUNCTION>
lastAvailable / lastNotAvailable parameters
When using the invocation $CMS_VALUE(IDENTIFIER.last)$ (if the menu group contains at least one menu level) the last menu level is output as the template fragment specified with the lastAvailable parameter.
If the menu group is empty the output is according to the template fragment specified with the lastNotAvailable parameter.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
...
<CMS_CDATA_PARAM name="lastAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="lastNotAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
...
</CMS_FUNCTION>
nextAvailable / nextNotAvailable parameters
When using the invocation $CMS_VALUE(IDENTIFIER.next)$ (if the menu group contains at least one other menu level) the next menu level is output as the template fragment specified with the nextAvailable parameter.
If no subsequent menu level is available or if the menu group is empty the output is according to the template fragment specified with the nextNotAvailable parameter.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
...
<CMS_CDATA_PARAM name="nextAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="nextNotAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
...
</CMS_FUNCTION>
previousAvailable / previousNotAvailable parameters
When using the invocation $CMS_VALUE(IDENTIFIER.previous)$ (if the menu group contains at least one previous menu level) the previous menu level is output as the template fragment specified with the previousAvailable parameter.
If no previous menu level is available or if the menu group is empty the output is according to the template fragment specified with the previousNotAvailable parameter.
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
...
<CMS_CDATA_PARAM name="previousAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="previousNotAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
...
</CMS_FUNCTION>
System object within the MenuGroup function
Within the function the system object #nav is available on which several methods can be invoked. To this end the instructions $CMS_VALUE(...)$ (output of the contents) or $CMS_REF(...)$ (resolution of a reference) can be used.
Overview
Attributes | Description |
---|---|
#nav.pos | Gives the position of the menu group in the menu group. |
#nav.ref | Returns a link to the corresponding menu level. |
#nav.label | Returns the value of the Menu name field of the menu level (from the Site Store). |
#nav.media | Returns the value of the Normal field of the menu level (from the Site Store). |
#nav.mediaHighlight | Returns the value of the with mouse pointer field of the menu level (from the Site Store). |
#nav.mediaSelected | Returns the value of the selected field of the menu level (from the Site Store). |
#nav.mediaHighlightSelected | Returns the value of the selected with mouse field of the menu level (from the Site Store). |
Return object of the function
Apart from the system object #nav, which is only valid within the function, each MenuGroup function returns a return object. The name of the object is the identifier assigned in resultname.
The following attributes can be accessed on the return object of the MenuGroup function:
Overview (attributes of the return object)
Attributes | Description |
---|---|
IDENTIFIER.directory | Is defined by the parameters delimiter, directoryRendering and directoryRenderingSelected. |
IDENTIFIER.first | Is defined by the parameters firstAvailable and/or firstNotAvailable. |
IDENTIFIER.groupSize | Total number of menu levels in the current menu group. These variables can be used to create expressions such as "Page X of Y". |
IDENTIFIER.last | Is defined by the parameters lastAvailable and/or lastNotAvailable. |
IDENTIFIER.next | Is defined by the parameters nextAvailable and/or nextNotAvailable. |
IDENTIFIER.pos | Position of the current menu level in the menu group. This attribute can be used to create expressions such as "Page X of Y". |
IDENTIFIER.previous | Is defined by the parameters previousAvailable and/or previousNotAvailable. |
Examples of the MenuGroup function
Several examples of use of the instruction within templates are shown in the following. The examples are intended to clearly show the specific effect of the instruction and provide help for the template developer when creating their own templates.
The examples displayed here must be adjusted for use within a project! For example, variable names must be changed to the specific variable names of the project in which the instruction is to be used. |
<CMS_HEADER>
<CMS_FUNCTION name="MenuGroup" resultname="fr_pt_menuGroup">
<CMS_CDATA_PARAM name="firstAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">|<</a>]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="firstNotAvailable"><![CDATA[|<]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="lastAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">>|</a>]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="lastNotAvailable"><![CDATA[>|]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="previousAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$"><</a>]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="previousNotAvailable"><![CDATA[<]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="nextAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">></a>]]></CMS_CDATA_PARAM>
<CMS_CDATA_PARAM name="nextNotAvailable"><![CDATA[>]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>
</CMS_HEADER>
$CMS_VALUE(fr_pt_menuGroup.first)$ $CMS_VALUE(fr_pt_menuGroup.previous)$ $CMS_VALUE(fr_pt_menuGroup.pos)$ / $CMS_VALUE(fr_pt_menuGroup.groupSize)$ $CMS_VALUE(fr_pt_menuGroup.next)$ $CMS_VALUE(fr_pt_menuGroup.last)$
The example outputs a simple menu group navigation:
<a href="/fs4preview/preview/30001/site/DE/current/30005/30453">|<</a>
<a href="/fs4preview/preview/30001/site/DE/current/30005/30451"><</a>
2 / 3
>
<a href="/fs4preview/preview/30001/site/DE/current/30005/30454">>|</a>