Start page / Template development / Variables / Contexts / project-related

Project-related contexts

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

Position of the variable definition

Context

Name

Project Settings

root

Global context

Generation schedules
(project properties)

root

Global context

Structure variables

SITE STORE

Site Store context

Generation schedules
(project properties)

SITE STORE

Site Store context

Page templates

PAGE

Page context

Section templates

section

Section context

   
Contents

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.

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

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.

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

Important #global.context can be used if a variable is to be set in other contexts and, therefore, its availability extended.
Important 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:

Contexts, Inheritance of variables in page and sections

Inheritance and overwriting variables in a page

Initial situation

Variables which are defined in a page (here: gv_var with value 1), can be accessed in all sections of the page.

Section 2 is based on a section template (“Section template 2”), in which the value of the variable gv_var is changed or overwritten, gv_var is for sections based on this section template 2.

In the sections with “Section template 1” on the other hand, the value defined in the page continues to apply to gv_var.

With this procedure, only localised overwriting of variables is possible, which always only applies to the template or in the objects (section, page, dataset, etc.) based on it, in which another value is defined for the variable. In this context, this is also called “overloading” the variable.

Contexts, global.context PAGE

Making variables available in other contexts

Using #global.context

In this example also, the variable gv_var is defined in the page with value 1.

In the section template, on which section 2 is based, (“Section template 2”) the value is changed to 2 and is written in the page context with #global.context:

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

The variable with this value can now be accessed in all other sections on this page, and in the page from the definition location.

Important In general: This possibility should only be used in exceptional cases because it may cause various problems (among other things unclear and confusing code flow, appearance of variable “from nowhere”, creating dependencies, lacking enclosure of functionalities etc.)
Important It should be noted that variables can be overloaded across object types.
Important To make variables from format templates and scripts in higher contexts available, see Special Variable Properties page.

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 template set 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"])$

© 2005 - 2022 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.1 | Data privacy