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

PageGroup

Especially when large amounts of information are to be displayed it can be advantageous to spread the information over several pages and therefore to structure it more clearly. FirstSpirit offers the option of grouping together several pages to form a page group and to manage them as a group.

Unlike menu groups which are automatically generated from the menu entries, page groups have to be explicitly defined within the Site Store. The members of the page group are defined by the allocation of individual pages to the group. The order of the pages relative to each other can be changed in any way required. An exception is pages generated by a content projection, i.e. by integrating a data source (content) in the Page Store. If more than one page is generated the pages are automatically part of a page group.

In order for structured navigation to be possible within the pages, navigation elements must be integrated on all pages which belong to the page 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 page group, whereby the current element can be displayed differently to the other elements (delimiter/directoryRendering/directoryRenderingSelected).

Syntax of the PageGroup function

The basic structure of the PageGroup function is as follows:

<CMS_FUNCTION name="PageGroup" 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>

Parameters of the PageGroup function

The PageGroup 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 fragment	Mandatory parameter
cycle	Cyclical page group	X	X	-	no
delimiter	Fragment for the separation of entries in the Table of Contents	-	-	X	no
directoryRendering	Fragment for unselected entries in the Table of Contents.	-	-	X	no
directoryRenderingSelected	Fragment for the selected entry in the Table of Contents.	-	-	X	no
firstAvailable	Fragment for the first page of the page group, if available.	-	-	X	no
firstNotAvailable	Fragment for the first page of the page group, if not available.	-	-	X	no
lastAvailable	Fragment for the last page of the page group, if available.	-	-	X	no
lastNotAvailable	Fragment for the last page of the page group, if not available.	-	-	X	no
nextAvailable	Fragment for the next page of the page group, if available.	-	-	X	no
nextNotAvailable	Fragment for the next page of the page group, if not available.	-	-	X	no
previousAvailable	Fragment for the previous page of the page group, if available.	-	-	X	no
previousNotAvailable	Fragment for the previous page of the page group, if not available.	-	-	X	no

cycle parameter

As a default a page group begins with the first page reference contained and ends with the last (cycle: 0).

If the cycle parameter is specified with value 1, the page group becomes an endless sequence of pages (cyclical page group), i.e. the last page is located in front of the first page and the first is after the last.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  <CMS_PARAM name="cycle" value="1" />
  ...
</CMS_FUNCTION>

delimiter / directoryRendering / directoryRenderingSelected parameters

When invoking the method $CMS_VALUE(VARNAME.directory)$ all pages of the page group are output as a table of contents.

The parameters directoryRendering (inactive pages) and directoryRenderingSelected (active/selected page) are decisive for display of the individual pages. To separate the output of the individual pages, the delimiter parameter can be used to define a template fragment. This fragment, apart from in front of the first page and after the last page, is also output between two directoryRendering- / directoryRenderingsSelected outputs.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  ...
  <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 page group contains at least one page) the first page is output as the template fragment specified with the firstAvailable parameter.

If the page group is empty the output is according to the template fragment specified with the firstNotAvailable parameter.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  ...
  <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 page group contains at least one page) the last page is output as the template fragment specified with the lastAvailable parameter.

If the page group is empty the output is according to the template fragment specified with the lastNotAvailable parameter.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  ...
  <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 page group contains at least one other page) the next page is output as the template fragment specified with the nextAvailable parameter.

If no subsequent page is available or if the page group is empty the output is according to the template fragment specified with the nextNotAvailable parameter.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  ...
  <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 page group contains at least one previous page) the previous page is output as the template fragment specified with the previousAvailable parameter.

If no previous page is available or if the page group is empty the output is according to the template fragment specified with the previousNotAvailable parameter.

<CMS_FUNCTION name="PageGroup" resultname="fr_pt_pageGroup">
  ...
  <CMS_CDATA_PARAM name="previousAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
  <CMS_CDATA_PARAM name="previousNotAvailable"><![CDATA[...]]></CMS_CDATA_PARAM>
  ...
</CMS_FUNCTION>

System object within the PageGroup 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 page in the page group.
#nav.media	Returns the picture entered in the Site Store for the sitemap.
#nav.ref	Returns a link to the corresponding page.
#nav.label	Returns the name of the corresponding page. This is either set in the Site Store (text for sitemap) or it is the name of the page from the Page Store.

Return object of the function

Apart from the system object #nav, which is only valid within the function, each PageGroup 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 PageGroup 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 pages in the current page group. This variable 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 page in the page 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 PageGroup 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="PageGroup" resultname="fr_pt_pageGroup">
    <CMS_CDATA_PARAM name="firstAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">|&lt;</a>]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="firstNotAvailable"><![CDATA[|&lt;]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="lastAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">&gt;|</a>]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="lastNotAvailable"><![CDATA[&gt;|]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="previousAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">&lt;</a>]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="previousNotAvailable"><![CDATA[&lt;]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="nextAvailable"><![CDATA[<a href="$CMS_REF(#nav.ref)$">&gt;</a>]]></CMS_CDATA_PARAM>
    <CMS_CDATA_PARAM name="nextNotAvailable"><![CDATA[&gt;]]></CMS_CDATA_PARAM>
  </CMS_FUNCTION>
</CMS_HEADER>
$CMS_VALUE(fr_pt_pageGroup.first)$ $CMS_VALUE(fr_pt_pageGroup.previous)$ $CMS_VALUE(fr_pt_pageGroup.pos)$ / $CMS_VALUE(fr_pt_pageGroup.groupSize)$ $CMS_VALUE(fr_pt_pageGroup.next)$ $CMS_VALUE(fr_pt_pageGroup.last)$

The example gives a simple page group navigation:

<a href="/fs4preview/preview/30001/site/DE/current/30005/30453">|&lt;</a> 
<a href="/fs4preview/preview/30001/site/DE/current/30005/30451">&lt;</a> 
2 / 3 
&gt; 
<a href="/fs4preview/preview/30001/site/DE/current/30005/30454">&gt;|</a>

Print version | Page start