FirstSpirit V5.1 Online Documentation

Start page / Advanced topics / Document groups

Document Groups

Document groups can be used to group together several independent page references to form a single unit and therefore cancel the hierarchical structure defined in the Site Store. In this way, for example, parts of the internet site can be grouped together to form a self-contained, linear document with separate layout. A frequent use case is PDF documents, which are generated from pages of the Site Store, including the title page, table of contents and chapter numbering.

Unlike content of normal page reference, content of a document group can not be edited in ContentCreator. Moreover, it is not possible to create a copy of a document group in ContentCreator.

Using document groups

In FirstSpirit SiteArchitect, Document Groups are created and managed in the Site Store.

The license.DOCUMENTGROUP parameter in the license file fs-license.conf must be set to the value “1” for use of this function

For further information on using Document Groups, please see FirstSpirit Documentation for SiteArchitect.

Using system objects

So-called system objects can be used to access information, data and objects within the templates. System objects are always context-dependent. Several specific system objects are available within the generation context, with which the generation of documents can be controlled from document groups.

System objects can be accessed everywhere, where methods can be called. Each system object starts with the character # and is expanded by the name of the respective system object. Different methods can be called, dependent on the type of system object. See also Chapter on System objects.

The following system objects can be used for document groups:

Using context variables

Apart from the system objects, other specific context variables exist for working with document groups. These context variables are user-specific variables with which the appearance of each node of a document group can be affected, i.e. fragments are added before or after a node.

PREFIX: This variable causes the following content to be shown in front of each node.
SUFFIX: This variable causes the following content to be shown after each node.

For menu levels, content is not shown via the SUFFIX variable until after the last child node of the menu level.

Possible uses of these two variables are explained in the following.

Start and end template

These templates contain only the frame for creating a valid document of the selected presentation channel.

Example: Start template in HTML

<CMS_HEADER></CMS_HEADER>
<html>
  <body>

Example: End template in HTML

<CMS_HEADER></CMS_HEADER>
</body>
</html>

If necessary, special functions like the creation of a “clickable” table of contents of the document group can be realized here.

Application examples

1st Example: Chapter headings

A simple way of implementing chapter headings is by using the page-specific PREFIX context variable.

This variable can be used to define FirstSpirit expressions before the actual content of each page reference or menu level:

<CMS_HEADER>
</CMS_HEADER>
$CMS_SET(PREFIX)$
  <br />
  <hr />
  <h$CMS_VALUE(#docNode.depth)$>
   Chapter&nbsp;$CMS_VALUE(#docNode.chapter)$&nbsp;
    $CMS_IF(!#docNode.label.isEmpty)$
      <a name="$CMS_VALUE(#docNode.label.convert2)$">
        $CMS_VALUE(#docNode.label.convert2)$
      </a>
    $CMS_END_IF$
  </h$CMS_VALUE(#docNode.depth)$>
  <hr />
$CMS_END_SET$

PREFIX is used here to define the structure of the chapter heading including anchors for the table of contents.

The system object #docNode is used to read out the respective information (depth in the tree, numbering of the page reference or menu level, headline of the node) of each current element of the document group.

2nd Example: List of Contents

The table of contents is usually needed once at the beginning of a document. The template fragment given below should therefore be copied into the start template:

<!-- Headline -->
<h1>
  <a name="summary"></a>
  $CMS_IF(#global.language.abbreviation == "DE")$
    &Uuml;bersicht
  $CMS_ELSE$
    Summary
  $CMS_END_IF$
  <br />
</h1>

<!-- Recursive loop -->
$CMS_SET(renderEntry)$
  <!-- All children (same level) -->
  $CMS_FOR(child, entries)$
    <!-- Indent -->
    $CMS_FOR(void, [0..(child.depth - 1)])$
        &nbsp;&nbsp;&nbsp;
    $CMS_END_FOR$

    <!-- Chapter -->
    $CMS_VALUE(child.chapter)$
    &nbsp;
    <!-- Label -->
    $CMS_IF(!child.label.isEmpty)$
      <a href="#$CMS_VALUE(child.label.convert2)$">
        $CMS_VALUE(child.label.convert2)$
      </a>
      <br />
    $CMS_END_IF$

    <!-- Recursive loop abort condition -->
    $CMS_IF(child.childs.size > 0)$
      $CMS_SET(entries, child.childs)$
      $CMS_VALUE(renderEntry)$
    $CMS_END_IF$
  $CMS_END_FOR$
$CMS_END_SET$

$CMS_SET(entries, #docGroup.childs)$
$CMS_VALUE(renderEntry)$
<br/>

The table of contents is introduced by the heading (in the section example: ).

This is then followed by recursive execution (in the section example: ).

In the  section, all children of a level are then considered and the chapter number and corresponding labelling is got for each element in the document group. To this end, the chapter name is output (from the page reference or the menu name) and is directly assigned a link:

<a href="#$CMS_VALUE(child.label.convert2)$">
        $CMS_VALUE(child.label.convert2)$
      </a>

Use of the convert2 function on the page group's text causes characters not conforming to HTML to be replaced by characters conforming to HTML through the conversion rule in the server properties (see FirstSpirit Manual for Administrators). In addition, inherent HTML characters (e.g. < (opening angle bracket) and > (closing angle bracket)) are quoted. To do this, the conversion rule must be supplemented to include the " symbol.

Finally, the abort condition for the recursion is given (in the section example: ).

The output could look like this:

Document group with numbering and labelling

3rd Example: Jump to table of contents

Especially in longer documents, it is frequently desirable to be able to jump to the table of contents at the end of a chapter.

In the following example, this function is achieved using a page-specific SUFFIX. The variable SUFFIX can be used to define FirstSpirit expressions after the actual content of a page reference or menu level. In the following example, it is output after rendering a page reference:

$CMS_SET(SUFFIX)$
  $CMS_IF(#docNode.isPageRef)$
    <a href="#summary">
      $CMS_IF(#global.language.abbreviation == "DE")$
        zur &Uuml;bersicht
      $CMS_ELSE$
        go to summary
      $CMS_END_IF$
    </a>
  $CMS_END_IF$
$CMS_END_SET$

4. Example: Local page references

For the preparation of links in document groups, it can be useful to decide whether a link remains within the document group or points outside the document group, e.g. to generate an internal PDF link.

The following expressions can be used for this:

$CMS_VALUE(#docGroup.contains("anExpression"))$
$CMS_VALUE(#docGroup.contains(myVar))$

To this end, either the UID (“Unified Identifier”) is transferred as a string or the page reference is transferred directly as an “object”. The return value of the “.contains(...)” expression is a Boolean value which, e.g. can be used for an If statement.

Print version | Page start