Start page
Start page

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

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

Important 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>

© 2005 - 2015 e-Spirit AG | All rights reserved. | Last change: 2014-07-21