Project-related contexts

The following contexts are relevant project-wide for work with variables in FirstSpirit:

In addition, there are a range of other contexts, which are not documented here because it is not possible to assure that they will not change in future versions of FirstSpirit. The concept of contexts introduced in the following can, in principle, be transferred to all contexts that can occur in FirstSpirit.

Several contexts do not have unique identifiers and can therefore overlap. For further information, see Special cases page.

One special cases is the system objects: several are globally available in the entire project (especially the system object #global), others are only available in certain types of template (the system object #cs for example, only available in table templates). The availability and use of the respective system objects is described in detail in the System objects chapter.

Overview

On this page the fundamental concept of contexts and the availability of variables in these contexts is introduced first:

• Reuse and inheritance of variables
• Where should a variable be defined?
• Visualization of context information

It is then shown how variable contexts can be modified:

• Overwriting variables (variable values)
• Making variables available in higher contexts (overloading)
  • Application example: Counting the sections of a page
  • Application example: Counting the sections of a page (incrementAndGet / AtomicInteger)
• Access to variables of other contexts

Reuse and inheritance

The contexts are arranged hierarchically and therefore enable variables to be passed down from a (higher) context to a lower one.

Regardless of a project's structure (pages with sections, pages with data sets, use of format templates, etc.), the root, SITE-STORE and PAGE contexts are always present. The section and cs contexts are only available if the relevant templates (section, table, format templates, etc.) are used.

Of the contexts available by default, root is the highest context, PAGE is the lowest:

1. root
2. SITE STORE
3. PAGE

All other contexts lie below PAGE.

Variable are in principle always available in the same context and in all lower contexts. (For details of the availability of variables within individual templates, see also page on template-related contexts.)

This means that variables defined in generation schedules or project settings are, for example, available in the entire project and therefore, e.g. these variables can be accessed in page and section templates. In sections and format templates it is possible to access variables set in pages, etc.

The following figure shows the availability of variables down to section level:

On the other hand, by default it is not possible to access variables set in sections in pages, as the page context is higher than the section context (see figure below, case 2). The arrow indicates the passing on/inheritance direction: In case 2, variables defined in the section are not passed on to the page.

Equally, a variable defined in one page template cannot be used in another page template. And the value, saved via the form of a page template, cannot be used in another page (instance) of the same page template (see figure below, case 3).

Where should a variable be defined?

In case 3 of the figure a variable, which is to be available in several pages, would have to be defined in a higher context, e.g. in the global context.

In a page template e.g. it is possible to access values set in the project settings for a variable, by using the variable name from the project settings.

Example
The variable ps_color is set in the project settings where it has the textual value #EFEFEF.
This value can be accessed in a page template, e.g. using

$CMS_VALUE(ps_color)$

Therefore, when drawing up a project concept or using variables, it is first necessary to take into account in which contexts a variable is to be available. Variables for content, which is to be available in several contexts, must be located in a higher context (e.g. root, SITE-STORE), so that it can be accessed in all lower level contexts (e.g. PAGE, section). However, to avoid overlapping in the variable definition, variables should always be defined in the lowest possible context.

Because, for the inheritance to work continuously across several contexts, the chosen variable names have to be unique throughout the entire project, otherwise overwriting can occur (name conflicts). If re-use of a variable in other (lower) contexts is not necessary, the same variable name can be used in different contexts, without resulting in conflicts.

#global.context can be used if a variable is to be set in other contexts and, therefore, its availability extended.

For more info, especially on the difference from variables that can be set in generation schedules, project settings and menu levels, see also Special Variable Properties page.

Visualization of context information

Which variables exist for a context, and which values are currently saved for these variables can be output with the call:

$CMS_VALUE(#global.dumpcontext)$

. In addition, a separator can also be given to separate the individual rows,e.g.

$CMS_VALUE(#global.dumpcontext("<br>"))$

This call is added in the output channel of the required template and then outputs the context information available in the current page.

If a variable can be found in several contexts, by default the variable in the lowest context is always taken into account. By giving the technical name of the required context and the required variable, it is possible to access the value of the variable in another context.

For example, to output the value of the “myVar” variable of the root context:

$CMS_VALUE(#global.context("root")["myVar"])$

See also section on Access to variables of other contexts.

For example, to save the “myVar” variable with value 2 in the PAGE context from a section template:

$CMS_SET(#global.context("PAGE")["myVar"], 2)$

See also section on Making variables available in higher contexts.

Overwriting variables (variable values)

A value, which is set for a variable in a higher context, can be overwritten in a lower context. This is done, e.g. with the following syntax:

$CMS_SET(ps_color, "#FF0000")$

The new defined value applies from the point at which the call named above takes place, and can then also be used in all lower contexts.

Making variables available in higher contexts (overloading)

By default, a variable in FirstSpirit is always available in the same context and in lower contexts.

In several cases it can be necessary to set a variable in a higher context, in order to increase the availability. This can be done using

#global.context("NAME")

. The placeholder NAME is used to give the context with the technical name, as given in the table shown above, in the middle column (“context”). The technical name of the context concerned can also be determined using the #global.dumpcontext method. If the variable is defined with different values in several contexts, by default the variable in the lowest context is always taken into account.

In this way, for example, a variable, which is defined in a section, and its value in the page context can be made available. This can also be used to access the variable in section of a pages which are based on another section template. The following diagrams show the use of #global.context schematically:

Application example: Count sections in a page
In this way, for example, the sections below a page can be counted in the Page Store.
To do this, for example, the COUNTER variable is defined first with start value 0 in the output channel of the page template:

$CMS_SET(COUNTER, 0)$

This variable is placed in the page context in the corresponding section template and is increased by 1:

$CMS_SET(#global.context("PAGE")["COUNTER"], COUNTER + 1)$

Each section, which is based on this section template and is added below the page with the variable definition given above, now increases the variable COUNTER by 1.

The variable can then be output again in the page template (after outputting the content area:

$CMS_VALUE(#global.page.body("IDENTIFIER"))$
Number of sections in this page: $CMS_VALUE(COUNTER)$

The output number is as high as the number of added sections.

The example code of the page template is therefore:

$CMS_SET(COUNTER, 0)$
$CMS_VALUE(#global.page.body("IDENTIFIER"))$
Number of sections in this page: $CMS_VALUE(COUNTER)$

The example code of the section template:

$CMS_SET(#global.context("PAGE")["COUNTER"], COUNTER + 1)$

Using incrementAndGet
Alternatively, the .incrementAndGet method can be used with AtomicInteger class.

To do this, instead of $CMS_SET(COUNTER, 0)$

the following is added in the page template:

$CMS_SET(COUNTER, class("java.util.concurrent.atomic.AtomicInteger").new)$

and the following is added to the section template:

$CMS_SET(gv_var, COUNTER.incrementAndGet)$

With the call

Number of sections in this page: $CMS_VALUE(COUNTER)$ 

the number of sections in the page which are based on the section template can in turn be output in the page template.

The example code of the page template is therefore:

$CMS_SET(COUNTER, class("java.util.concurrent.atomic.AtomicInteger").new)$
$CMS_VALUE(#global.page.body("IDENTIFIER"))$
Number of sections in this page: $CMS_VALUE(COUNTER)$

The example code of the section template:

$CMS_SET(gv_var, COUNTER.incrementAndGet)$

Access to variables of other contexts

#global.context can also be used to access variables of other contexts, namely using $CMS_VALUE(...)$.

In the following example, firstly, a variable (myVar) is defined in a page template and different values are assigned to it for different contexts:

$CMS_SET(#global.context("root")["myVar"], "Value in the root context")$
$CMS_SET(myVar, "Value in the PAGE context")$

The different values of the contexts can be accessed again in the page template by giving #global.context:

PAGE: $CMS_VALUE(myVar)$ </br>
root: $CMS_VALUE(#global.context("root")["myVar"])$