Special variable properties

Having described the concept of variables and contexts in FirstSpirit on the previous page, in the following special features of several variables and their definition location are introduced:

• Variables in schedules, project settings and menu levels
• Variables in format templates
• Variables in Global Content Areas
• Variables in nested input components
  (for example, FS_LIST)

Variables in schedules, project settings and menu levels

As the table on the previous page shows, the SITE-STORE and root contexts have points of intersection or overlap.

In the preview the variables are evaluated in the following order:

1. Structure variables
2. Variables in project settings

If a variable is defined in the project properties and in menu levels with the same name, it is available not only in the root context (here the value assigned via the project settings applies) but also in the SITE-STORE context (here the value assigned via the menu level applies). Without applying #global.context(...) (see page on Project-related contexts), the value assigned for the variable via the menu level is output in the preview, because by default the variable in the lowest context is taken into account.

In the case of structure variables, it must also be noted that they are only displayed in the preview of page references (i.e. Site Store), but not in the preview of pages (Page Store).

Structure variables on a generated page can be overwritten by schedule variables: If job variables are set, they are read out on the generated page and overwrite variables with the same name, which are defined on the root node of the Site Store or in the project settings.

Only variables, which are defined at the root node level of the Site Store are overwritten. In the following cases, structure variables are not overwritten by schedule variables with the same name: - structure variables, which are defined at menu levels, which lie below the root node, - structure variables, which are defined at root node level, but have been changed on a lower menu level. See also the Structure variables page.

This can, e.g. be used to achieve a difference between the preview and the generated website (or parts of it, "Generate partial project" schedule) or between different generation schedules.

If variables from the project settings are to be evaluated during the generation, neither schedule nor structure variables may be set.

Fig. 1: Site Store context versus Global context (click to enlarge)

Examples of the overwriting of variables:
If the variable A is defined in a menu level, in the project settings and in a generation schedule, each with different values, the value in the preview is the value defined in the Site Store, the value on the generated page is the value defined in the schedule (however, only for values defined at the root node level of the Site Store, Fig.1 : case 1 and 2).

If no schedule variable is defined, the value defined in the Site Store is applied to the generated page (case 3).

Only if neither a schedule nor a structure variable are defined, the value from the project settings is used (case 4).

Variables in format templates

Content of format templates or scripts can be integrated in other template types (e.g. page or section templates) using the instruction $CMS_RENDER(...)$ in combination with the parameter template or script, e.g.

$CMS_RENDER(template:"IDENTIFIER")$

The IDENTIFIER is the abbreviation of the format template or script, which is to be integrated.

Setting and outputting variables in format templates
Due to the availability of variables in lower contexts, it is also possible to access e.g. variables, which are available in page or section templates, in format templates: E. g. if the gv_page variable is defined in a page template:

$CMS_SET(gv_page, "Variable in the page context")$                                                                                                         (Page template)

This variable can be accessed in a format template integrated in the page template (via the $CMS_RENDER(...)$ call) and therefore output, e.g. via

$CMS_VALUE(gv_page)$                                                                                                                                                        (Format template)

As already shown before, here it is of course important to define the variable gv_page before the $CMS_RENDER(...)$ call

Variables which are defined in format templates, on the other hand, are by default not available in the (higher) page context. This means, variables which are defined in format templates cannot be accessed in page templates. The output can therefore only be made via the format template itself, not via the page template.

E.g. if the variable gv_form is defined in a format template

$CMS_SET(gv_form, "Variable in the format template context")$                                                                                (Format template)

it can only be output in the format template, e.g. via

$CMS_VALUE(gv_form)$                                                                                                                                                        (Format template)

To make a variable defined in a format template also available in the page context, the $CMS_RENDER(...)$ call can be supplemented with the context:"this" parameter.

However, here it must be noted that in this way, variables in another context can be involuntarily overwritten.

E.g. if the variable gv_form is defined in a format template:

$CMS_SET(gv_form, "Variable in the format template context")$                                                                                (Format template)

it can be accessed via the following $CMS_RENDER(...)$ call in the page template

$CMS_RENDER(template:"IDENTIFIER", context:"this")$                                                                                                     (Page template)

and therefore output, e.g. via

$CMS_VALUE(gv_form)$                                                                                                                                                            (Page template)

The same of course also applies to section templates and scripts.

Variables in Global Content Areas

Fig. 2: Structur of Global Content Areas

Content of a Global Content Area (and, if applicable, the sections integrated in a global page) is output in the required template with $CMS_VALUE(#global.gca("IDENTIFIER"))$. Here, in place of the IDENTIFIER placeholder, the reference name of the Global Content Area page that is to be output must be provided. Instead of calling $CMS_VALUE(#global.gca("IDENTIFIER"))$, the content of the corresponding template is added and the context of the global page begins. Therefore, contexts are nested here.

Fig. 2 shows, in simplified form, the structure of a page with a section in the Page Store ("PS") with a page and a section from the Global Content Area ("GCA"). Accordingly, here too it is possible to talk of "outer" elements (e.g. the page in the Page Store) and "inner" elements (e.g. the section in the Global Content Areas).

Fig. 3: Contexts of Global Content Areas

As a result of this nesting, the contexts of the sections can overlap or overwrite each other, as e.g. section (PS) and section (GCA) each have a context with the name section. Page (PS) and page (GCA) on the other hand each have their own context. In this case, with #global.context("section") only the context of the "innermost" section is always addressed and therefore in general the section from the Global Content Area.
#global.page.id and #global.page.name or #global.page.uid, or #global.section.id and #global.section.name can each be used to output the ID and the reference name of the page or the section from the Page Store or from the Global Content Area, respectively.

Variables, which are defined in the page and section templates, on which the pages (PS) and (GCA) or sections (PS) and (GCA) are based, are by default valid for the current page or the current section and for all internal elements. If a variable is also to be made available in the external elements, #global.context("PAGE") can be used.

If variables with the same identifier are defined in the page and section templates, the variable of the current element always applies. This means, the variables defined in this template can be accessed using the familiar instructions (see also Variables in templates page).

Unique variable identifiers should be selected in the templates to ensure that the variables of the current other elements can be accessed via each of the templates for the page and sections from the Page Store and from the Global Content Area.

Variables in nested input components

Fig. 4: Nested input components (click to enlarge)

Fig. 5: Contexts of nested input components

The content of FS_LIST is output in the required template with $CMS_VALUE(IDENTIFIER)$. The variable identifier of FS_LIST must be given for the placeholder IDENTIFIER In the example in Fig. 4, e.g. sections A and B each contain an FS_LIST component, whose content is output in section A and B respectively. At the place where $CMS_VALUE(IDENTIFIER)$ is called, the context of the "next", inner section begins (see also Fig. 5).

As a result of this nesting, the contexts of the sections can overlap or be overwritten.

In the example of FS_LIST the outer and the inner sections, e.g. have a common context with the technical identifier section. At the same time, by default all variables defined in the corresponding section template, or in a higher context, can be accessed in each section, regardless of whether it is the outer or an inner section, by giving the variable identifier. If a variable exists in several contexts with the same identifier (a variable with the same identifier is, e.g. defined in an inner and the outer section or in the page), the variable of the current section is always accessed.

If a variable is also to be made available in outer sections, this can be done using

$CMS_SET(#global.context.parentContext.parentContext["VALUE"], IDENTIFIER)$ 

(see also #global.context("NAME")).

Unique variable identifiers should be selected in these section templates to ensure that both the variables of the current sections and the other sections can be accessed via each of the section templates for the outer and inner sections.

To avoid infinite loops, creating an inner section with the same section template as the outer section should be prevented. The TEMPLATES / TEMPLATE tags can be used to limit the number of section templates that can be selected.

This context concept also applies in principle to CMS_INPUT_CONTENTAREALIST. The number of section templates that can be selected can be limited with the help of the SOURCES / TEMPLATE tags.