Start page / Template development / Template syntax / Functions / in the header / Navigation

Navigation

The Navigation function is used to display the page structure specified by the Site Store on the generated pages. The navigation output is defined in the page template by the Navigation function. The menu levels created in the Site Store are automatically adopted. The individual parameters can be used to display different types of navigation. The basic structure of the function always remains the same, irrespective of whether it is a graphic or a text navigation.

Example:

<CMS_FUNCTION name="Navigation" resultname="nav">
  <CMS_PARAM name="expansionVisibility" value="standard" />
  <CMS_PARAM name="wholePathSelected" value="1" />
  <CMS_ARRAY_PARAM name="unselectedHTML">
    <CMS_ARRAY_ELEMENT><![CDATA[...]]></CMS_ARRAY_ELEMENT>
    <CMS_ARRAY_ELEMENT><![CDATA[...]]></CMS_ARRAY_ELEMENT>
    <CMS_ARRAY_ELEMENT><![CDATA[...]]></CMS_ARRAY_ELEMENT>
  </CMS_ARRAY_PARAM>
  <CMS_ARRAY_PARAM name="selectedHTML">
    <CMS_ARRAY_ELEMENT index="0..3"><![CDATA[...]]></CMS_ARRAY_ELEMENT>
  </CMS_ARRAY_PARAM>
</CMS_FUNCTION>

If the navigation functions are created in the header area of the page template the function results must be output within the HTML area. Here the return value of each navigation function is output at the required position with a $CMS_VALUE(...)$ instruction.

If several, spatially separated navigations are to be arranged on a page, a separate navigation function for each sub-navigation must be created in the header area of the page template and output in the HTML area. For example, if there are two navigations for a main menu and a sub-menu on the page, navigation functions must be stored in two different locations in the page template.

Example:

<!-- 1st Navigation -->
$CMS_VALUE(fr_pt_mainnav)$
<!-- 1st Navigation end -->
<!-- 2nd Navigation -->
$CMS_VALUE(fr_pt_subnav)$
<!-- 2nd Navigation end -->

Syntax of the Navigation function

The basic structure of the Navigation function is as follows:

<CMS_FUNCTION name="Navigation" resultname="IDENTIFIER">
  <CMS_PARAM name="expansionVisibility" value="KEYWORD" />
  <CMS_PARAM name="wholePathSelected" value="BOOLEAN_VALUE" />
  <CMS_PARAM name="selectedNode" value="IDENTIFIER" />
  <CMS_PARAM name="root" value="IDENTIFIER" />
  <CMS_PARAM name="siteMap" value="BOOLEAN_VALUE" />
  <CMS_PARAM name="menuFirst" value="BOOLEAN_VALUE" />
  <CMS_PARAM name="suppressEmptyFolders" value="BOOLEAN_VALUE" />
 <CMS_ARRAY_PARAM name="beginHTML">
    <CMS_ARRAY_ELEMENT><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="innerBeginHTML">
    <CMS_ARRAY_ELEMENT index="INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="unselectedHTML">
    <CMS_ARRAY_ELEMENT index="INTEGER..INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="selectedHTML">
    <CMS_ARRAY_ELEMENT><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="pageRefRendering">
    <CMS_ARRAY_ELEMENT index="INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="delimiter">
    <CMS_ARRAY_ELEMENT index="INTEGER..INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="selectedDelimiter">
    <CMS_ARRAY_ELEMENT><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="innerEndHTML">
    <CMS_ARRAY_ELEMENT index="INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
        ...
  </CMS_ARRAY_PARAM>
 <CMS_ARRAY_PARAM name="endHTML">
    <CMS_ARRAY_ELEMENT index="INTEGER..INTEGER"><![CDATA[VALUE]]></CMS_ARRAY_ELEMENT>
    ...
  </CMS_ARRAY_PARAM>
</CMS_FUNCTION>

Navigation function parameters

The following parameters can be used in the Navigation function:

beginHTML
delimiter
endHTML
expansionVisibility
innerBeginHTML
innerEndHTML
menuFirst
pageRefRendering
root
selectedDelimiter
selectedHTML
selectedNode
siteMap
suppressEmptyFolders
unselectedHTML
wholePathSelected

The expansionVisibility parameter is a mandatory parameter. All other parameters are optional. However, the unselectedHTML and selectedHTML parameters should be used once so that the navigation items are visible.

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	Specifying a constant	Specifying expressions	Specifying a template fragment	Mandatory parameters
beginHTML	-	-	X	no
delimiter	-	-	X	no
endHTML	-	-	X	no
expansionVisibility	X	O	-	no
innerBeginHTML	-	-	X	no
innerEndHTML	-	-	X	no
menuFirst	X	O	-	no
pageRefRendering	-	-	X	no
root	X	O	-	no
selectedDelimiter	-	-	X	no
selectedHTML	-	-	X	no
selectedNode	X	O	-	no
siteMap	X	O	-	no
suppressEmptyFolders	X	O	-	no
unselectedHTML	-	-	X	no
wholePathSelected	X	O	-	no

expansionVisibility parameter

The expansionVisibility parameter specifies how the expanded areas of the navigation are to be handled, i.e. how a navigation is to be pulled down/folded out. The following table gives an overview of which values these parameters can accept and which effect the individual keywords have.

For the purposes of improved understanding a graphic has been deposited for each keyword.

The graphics represent the visible areas of the tree with orange coloured squares and the invisible areas with grey circles, if the corresponded keyword is used on the selected page (large orange coloured square).

Example:

<CMS_PARAM name="expansionVisibility" value="all" />

All elements of the first menu level are completely displayed.

Keywords for expansionVisibility:
standard	With the keyword standard the navigation is completely contracted. The current menu item, its children, its siblings, its parents and their siblings are displayed.
all	If the keyword all is selected as the value the complete navigation tree is completely expanded and all elements are displayed.
pathonly	The keyword pathonly causes only the current menu item, its children and all its parents to be displayed.
purepath	The keyword purepath to a large extent corresponds to the parameter pathonly, only that the children of the current menu item are hidden. This navigation therefore displays the path to the current menu item only.
parentpath	The keyword parentpath to a large extent corresponds to the parameter purepath, only that with parentpath the setting of "Display in navigation menu?" on the tab "Names" of menu levels is evaluated additionally. If, for example, the option "Display in navigation menu?" is deactivated for a menu level and parentpath is set, starting from the root node, the path is output only up to the last visible menu level. I.e., the first menu level starting from the root node with "Display in navigation menu?" option disabled and all menu levels below it are not displayed.
subtree	The subtree parameter causes only the sub-tree concealed under the current menu item (inclusive) to be displayed. There are two possibilities to display the current menu item : An additional navigation function using the keyword standard for the expansionVisibility parameter. The wholePathSelected parameter should not be given. Furthermore, only template fragments should be created by using the selectedHTML parameter. Accessing the menu level via the system object #global (e.g. with $CMS_VALUE(#global.node.parent)$). Note: If the subtree parameter (expansionVisibility="subtree") is set, a starting point set via the root parameter will not be taken into account.

menuFirst parameter

The menuFirst parameter is used to specify whether, in the output of the navigation, the menu levels are to be output first (value: 1; default value) or whether the page references (value: 0) are to be output.

<CMS_PARAM name="menuFirst" value="1" />

The parameter only has an effect if the parameter siteMap has been specified too.

root parameter

The root parameter defines the starting point of the navigation.

Either a folder or a page can be specified as the starting point.

A folder is specified with the keyword pagefolder: followed by the folder's identifier:

<CMS_PARAM name="root" value="pagefolder:IDENTIFIER" />

A page reference is specified with the keyword pageref: followed by the page reference's identifier:

<CMS_PARAM name="root" value="pageref:IDENTIFIER" />

When specifying a page reference the menu level above the page reference (= parent) is deemed to be the starting point.

If the root parameter is not given the root of the Site Store is taken as the starting point of the navigation.

If the root parameter is specified the level counting changes.
Level 0 of the navigation is then deemed to be the immediate children of the given node.

The root parameter will not be taken into account if the subtree parameter (expansionVisibility="subtree") is set as well.

selectedNode parameter

By specifying the selectedNode parameter a folder or a page can be defined which the navigation is to view as being the current or selected element.

A folder is specified with the keyword pagefolder: followed by the folder's identifier:

<CMS_PARAM name="selectedNode" value="pagefolder:IDENTIFIER" />

A page is specified with the keyword pageref: followed by the page reference's identifier:

<CMS_PARAM name="selectedNode" value="pageref:IDENTIFIER" />

siteMap parameter

If the parameter siteMap is given the value 1 the page references are also output in the navigation.

If the parameter is not set or if the value 0 is specified only menu levels from the Site Store are output.

<CMS_PARAM name="siteMap" value="1" />

Output of the page references is specified by the parameter pageRefRendering .

suppressEmptyFolders parameter

The suppressEmptyFolders parameter can be used to suppress menu levels which do not contain any page references in the output.

The value 1 suppresses the output of menu levels without page references and 0 (= default value) does not.

<CMS_PARAM name="suppressEmptyFolders" value="1" />

wholePathSelected parameter

If the value of the parameter wholePathSelected is specified as 1 the whole path from the current element up to the root (parent chain) is deemed to have been selected. This is required, for example, to display this element in a different colour to the unselected elements of the navigation.

If wholePathSelected is given with 0 or if the parameter has not been set, only the element immediately higher than the page reference (the parent or menu level) is deemed to have been selected (= default value).

Example:

<CMS_PARAM name="wholePathSelected" value="1" />

All elements of the parent chain (all parents up to the root) are deemed to be selected. Output of the selected and unselected elements is specified by the parameter selectedHTML and unselectedHTML .

Output fragments

Within the output fragments (<CMS_ARRAY_PARAM>-Tags) the <CMS_ARRAY_ELEMENT> tag determines the way in which the navigation is displayed in the browser. A separate <CMS_ARRAY_ELEMENT> tag is created for each navigation level to be displayed.

The optional attribute index can be specified for each level. This attribute is used to specify the level to which this entry is to apply. The level counting begins with 0. Therefore, 0 is the highest level. If no index attribute has been specified the level is automatically calculated, i.e. the first entry without index is interpreted as 0, the second as 1 etcetera. In addition, an area definition can be given for index , e.g. 0..2 (from 0 to 2).

Example:

<CMS_ARRAY_PARAM name="selectedHTML">
   <CMS_ARRAY_ELEMENT index="0">
      <![CDATA[<a href="$CMS_REF(#nav.ref)$" ...">$CMS_VALUE(#nav.label)$</a>]]>
   </CMS_ARRAY_ELEMENT>
</CMS_ARRAY_PARAM>

Each menu item of a navigation usually links to a new page. This means: each array element needs a <![CDATA[...]]> tag to insert a link. A link can be entered within the <![CDATA[...]]> tag with <a href=““>...</a>. However, as the link is not always to be to the same page, a reference to an object from the Site Store is required instead of a constant page.

If the root parameter is specified the level counting changes.
Level 0 of the navigation is then deemed to be the immediate children of the given node.

beginHTML / endHTML parameters

The two parameters beginHTML and endHTML can be used to define template fragments for each individual level of the navigation, each of which are output in front of (beginHTML) or after (endHTML) an element. This means each entry of the corresponding level and all its sub-items are enclosed by these two parameters.

<CMS_ARRAY_PARAM name="beginHTML">
  ...
</CMS_ARRAY_PARAM>

<CMS_ARRAY_PARAM name="endHTML">
  ...
</CMS_ARRAY_PARAM>

delimiter / selectedDelimiter parameters

While the parameters beginHTML and endHTML are invoked for each individual entry in the navigation, the content of the delimiter parameter can only be output between two elements of the navigation on the same level.

The selectedDelimiter parameter can be used to define a template fragment which is only output in front of and after the selected entry of the navigation in the respective level.

The content of the selectedDelimiter parameter is not output in front of the first and not after the last element in a level.

If the selectedDelimiter parameter is not given, but only the delimiter parameter, the content of the delimiter parameter is displayed between all entries of the navigation.

If the selectedDelimiter parameter is used only, the content of the parameter is only output around one selected element of the navigation.

The delimiter and selectedDelimiter parameters are only used if the siteMap parameter is not given or its value is 0 .

<CMS_ARRAY_PARAM name="delimiter">
  ...
</CMS_ARRAY_PARAM>

<CMS_ARRAY_PARAM name="selectedDelimiter">
  ...
</CMS_ARRAY_PARAM>

innerBeginHTML / innerEndHTML parameters

The two parameters innerBeginHTML and innerEndHTML can be used to specify further template fragments which are to include all children of a navigation entry.

<CMS_ARRAY_PARAM name="innerBeginHTML">
  …
</CMS_ARRAY_PARAM>

<CMS_ARRAY_PARAM name="innerEndHTML">
   ...
</CMS_ARRAY_PARAM>

selectedHTML / unselectedHTML parameters

The selectedHTML and unselectedHTML parameters are used to define the template fragments to be used in the output of an element. Here selectedHTML specifies the output of selected elements and unselectedHTML specifies the output of unselected elements.

Example:

<CMS_ARRAY_PARAM name="selectedHTML">
  …
</CMS_ARRAY_PARAM>

<CMS_ARRAY_PARAM name="unselectedHTML">
   ...
</CMS_ARRAY_PARAM>

The selection behaviour is influenced by the selectedNode and wholePathSelected parameters.

pageRefRendering parameter

Use of the parameter pageRefRendering is analogous to the parameters selectedHTML and/or unselectedHTML. The difference is that the template fragment given by the parameter pageRefRendering is output for all page references of a menu level.

This parameter is only taken into account if the parameter siteMap has been given!

<CMS_ARRAY_PARAM name="pageRefRendering">
  …
</CMS_ARRAY_PARAM>

System object within the Navigation function

Within the Navigation 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.

The system object #nav can be used for example to enter links within the <![CDATA[...]]> tags. As constant values are not to be given here, default variables are used instead.

Example:

"$CMS_REF(#nav.ref)$"
$CMS_VALUE(#nav.label)$

Overview

Attributes	Description
#nav.comment	Comment on the target node entered in the Site Store.
#nav.data("IDENTIFIER")	Returns the value of the variables given with the identifier from the Site Store.
#nav.hasSubFolders	Determines whether the current navigation item has got children (sub-ordinated menu levels / folders)
#nav.id	Unique server-wide valid identification number of the target node.
#nav.isFirst	Returns whether the navigation element is the first of the current menu level.
#nav.isLast	Returns whether the navigation element is the last of the current menu level.
#nav.label	Name of the corresponding target node.
#nav.level	Number of the navigation level. The counting begins with 0
#nav.levelPos	Position of the current folder in the current level. The counting begins with 0.
#nav.media	Picture selected in the Site Store for the field Normal.
#nav.media.height	Height of the picture in pixels.
#nav.media.width	Width of the picture in pixels.
#nav.mediaHighlight	Picture selected in the Site Store for the field with mouse pointer.
#nav.mediaHighlight.height	Height of the picture in pixels.
#nav.mediaHighlight.width	Width of the picture in pixels.
#nav.mediaHighlightSelected	Picture selected in the Site Store for the field selected with mouse.
#nav.mediaHighlightSelected.height	Height of the picture in pixels.
#nav.mediaHighlightSelected.width	Width of the picture in pixels.
#nav.mediaSelected	Picture selected in the Site Store for the field selected.
#nav.mediaSelected.height	Height of the picture in pixels.
#nav.mediaSelected.width	Width of the picture in pixels.
#nav.positions[INTEGER]	Position of the corresponding folder in the level given with an integer. #nav.positions is a list. It is therefore necessary to ensure that the number given is less than the number of elements in the list (#nav.positions.size).
#nav.ref	Reference to the target node or the corresponding start node.
#nav.ref.page.id	Unique server-wide valid identification number of the corresponding page.
#nav.selected	Determines whether the element is selected or not.

#nav.comment

This method invocation is used to output the comment which can be entered, language-dependent, in the Comment field in a menu level of the Site Store.

Example:

<img name=... src=... alt="$CMS_VALUE(#nav.comment)$">

#nav.id

With the method invocation #nav.id the unique identification number of the node from the Site Store is returned.

A unique identification number is frequently used for the generation of onMouseOver effects (JavaScript).

Example:

<img name="i$CMS_VALUE(#nav.id)$" src="...">

#nav.label

With the method invocation #nav.label the text allocated to the respective menu entry is returned.

The method invocation is usually used in the following parameters:

pageRefRendering
selectedHTML
unselectedHTML

Example:

<a  href="$CMS_REF(#nav.ref)$" target="_blank">$CMS_VALUE(#nav.label)$</a>

#nav.ref

With the method invocation #nav.ref the link to the page reference from the Site Store allocated to the respective menu entry is returned.

The method invocation is usually used in the following parameters:

pageRefRendering
selectedHTML
unselectedHTML

Example:

<a  href="$CMS_REF(#nav.ref)$" target="_blank">$CMS_VALUE(#nav.label)$</a>

#nav.ref.page.id

This method invocation can be used to output the identification number of the page from the Page Store to which the page reference refers.

The method invocation can only be used within the pageRefRendering parameter.

The parameter pageRefRendering is only evaluated if the siteMap parameter has been given.

The identification number is required, for example, for the generation of a PDF table of contents.

Example:

<img name="i$CMS_VALUE(#nav.ref.page.id)$" src="...">

Examples of the Navigation 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="Navigation" resultname="nav">
    <CMS_PARAM name="expansionVisibility" value="standard" />
    <CMS_ARRAY_PARAM name="innerBeginHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[<ul>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
    <CMS_ARRAY_PARAM name="beginHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[<li>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
    <CMS_ARRAY_PARAM name="unselectedHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[<a href="$CMS_REF(#nav.ref)$">$CMS_VALUE(#nav.label)$</a>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
    <CMS_ARRAY_PARAM name="selectedHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[<a href="$CMS_REF(#nav.ref)$" style="color:#ff0000;">$CMS_VALUE(#nav.label)$</a>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
    <CMS_ARRAY_PARAM name="endHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[</li>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
    <CMS_ARRAY_PARAM name="innerEndHTML">
      <CMS_ARRAY_ELEMENT index="0..4"><![CDATA[</ul>]]></CMS_ARRAY_ELEMENT>
    </CMS_ARRAY_PARAM>
  </CMS_FUNCTION>
</CMS_HEADER>
$CMS_IF(!nav.isEmpty)$
  <ul>
    $CMS_VALUE(nav)$
  </ul>
$CMS_END_IF$

The example outputs a simple navigation as a list, whereby the selected element is coloured red.

Exemplary output:

<ul>
  <li>
    <a href="/fs4preview/preview/671041/site/DE/current/671044/897047">entry_01</a>
  </li>
  <li>
    <a href="/fs4preview/preview/671041/site/DE/current/671044/675058">entry_02</a>
  </li>
  <li>
    <a href="/fs4preview/preview/671041/site/DE/current/671044/897043">entry_03</a>
    <ul>
      <li>
        <a href="/fs4preview/preview/671041/site/DE/current/671044/897049" style="color:#ff0000;">entry_03_01</a>
      </li>
      <li>
        <a href="/fs4preview/preview/671041/site/DE/current/671044/897050">entry_03_02</a>
      </li>
    </ul>
  </li>
</ul>

Print version | Page start