Special variable properties
After displaying the variable and context concept in FirstSpirit on the previous pages, features of some variables and where they are defined will be presented in the following:
- Variables in schedules, project settings and menu levels
- Variables in format templates
- Variables in link templates (such as in the DOM editor)
- Variables in the Global content area
Variables in schedules, project settings and menu levels
As the table on the previous page shows, the contexts SITE-STORE and root have overlapping points.
The variables are evaluated in the preview in the following order:
- Structure variables
- Variables in project settings
If a variable is defined in the project settings and in menu levels with the same name, it is available in both the root context (here the value assigned via the project settings is used) and in the SITE-STORE context (here the value assigned via the menu level is used). Without using #global.context(...) (see the Project-related contexts page), the value assigned via the menu level is output in the preview for the variable, since by default the variable in the lowest context is taken into account.
In the case of structure variables, it is also important to note that they are displayed only in the preview of page references (also Site Store), but not of pages (Page Store).
Structure variables on a generated page can be overwritten by schedule variables: if schedule variables are set, they are read out on the generated page and overwrite variables with the same name that are defined on the root nodes of the Site Store or in the project settings.
 |
Only variables that 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 defined at the menu level that are under the root node, - structure variables defined at the root node level, but that have been changed at the menu level below it. Refer also to the page on Structure variables. |
For instance, this can be used to obtain 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 evaluated during generation, neither schedule nor structure variables are permitted to be set.
Fig. 1: Site Store context vs. global context (click to enlarge)
Examples of overwriting variables:
If the variable A in a menu level, in the project settings and in a generation schedule is defined using different values for each, the value defined in the Site Store applies in the preview, and the value defined in the schedule applies on the generated page (although only for values defined at the root node level of the Site Store, Fig. 1 : cases 1 and 2).
If no schedule variable is defined, the value defined in the Site Store applies on the generated page (case 3).
The value of the variable from the project settings is used only if no schedule or structure variables are defined (case 4).
Making variables from schedules available in project settings
Variables defined in generation schedules (see also Execute generation (→Documentation for Administrators)) are not available in the project settings by default.
They can be made available in the project settings page as follows:
Transfer variables from the generation schedule to a map (on the output tab of the template for the project settings):
$CMS_SET(generationTaskVariables,{:})$
$CMS_IF(!#global.preview)$
$CMS_FOR(var,#global.scheduleContext().getTask().getVariables())$
$CMS_SET(void,generationTaskVariables.put(var.getKey(),var.getValue()))$
$CMS_END_FOR$
$CMS_END_IF$Access is then possible via
generationTaskVariables.<Name of the variable from the generation action of the schedule>
e.g.,
$CMS_VALUE(generationTaskVariables.<Name of the variable from the generation action of the schedule>)$
The variable should be secured with a fallback value in case the variable is not set in the output, e.g.:
$CMS_VALUE(generationTaskVariables.target, default:"development")$
This means that either the value of the target variable from the schedule generation action is output (see figure) or the development string (from the project settings page template) if the variable was not set in the relevant schedule or no schedule is used (e.g., in the preview).
Variables in format templates
The content of format templates or scripts can be integrated in other template types (such as page or section templates) using the $CMS_RENDER(...)$ instruction in combination with the template or script parameter; for example:
$CMS_RENDER(template:"IDENTIFIER")$
The IDENTIFIER is the abbreviation for the format template or script 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 variables, for instance, that are present in page or section templates within format templates: if, for instance, the variable gv_page is defined in a page template:
$CMS_SET(gv_page, "Variable in page context")$ (page template)
it can be accessed in a format template integrated in the page template using the $CMS_RENDER(...)$ call and thus output, for example, using
$CMS_VALUE(gv_page)$ (format template)
|
As already shown previously, it is of course important to define the variable gv_page before the $CMS_RENDER(...)$ call. |
Variables defined in the format templates, however, are by default not available in the (higher) page context. This means that variables that are defined in format templates cannot be accessed in page templates. It is therefore only possible to output via the format template itself and not via the page template.
If, for instance, the variable gv_form is defined in a format template:
$CMS_SET(gv_form, "Variable in format template context")$ (format template)
it can only be output via the format template; for example:
$CMS_VALUE(gv_form)$ (format template)
To make a variable that has been defined in a format template available in a page context as well, the context:"this" parameter can be added to the $CMS_RENDER(...)$ call.
|
However, when doing so, it is important to note that variables made available this way can be unintentionally overwritten in a different context. |
If, for instance, the variable gv_form is defined in a format template:
$CMS_SET(gv_form, "Variable in format template context")$ (format template)
it can be accessed in the page template using the following $CMS_RENDER(...)$ call:
$CMS_RENDER(template:"IDENTIFIER", context:"this")$ (page template)
and thus output, for instance, using
$CMS_VALUE(gv_form)$ (page template)
The same of course also applies to section templates and scripts.
Variables in links
Another common use case for nested contexts is to use link templates in the DOM editor (CMS_INPUT_DOM).
Fig. 2: Contexts in links
By default, links inherit variables in DOM editors from higher contexts, i.e. variables that were previously initialized, for instance in the page or a section in which the DOM editor is used with a link template, can be used in the link template itself. Fig. 2 is a schematic drawing showing the validity of variables/values in link templates within a DOM editor.
This shows the validity of variables when they are initialized in a form or template set:
- pt_var_form: a variable initialized in the form of a page template
- pt_var_out: a variable initialized in the template set of a page template (e.g. via $CMS_SET(...)$)
- st_var_form: a variable initialized in the form of a section template, specifically in the CMS_INPUT_DOM input component
- st_var_out: a variable initialized in the template set of a section template (e.g. via $CMS_SET(...)$)
- link_var_form: a variable initialized in the form of a link template
- link_var_out: a variable initialized in the template set of a link template
|
In the link template, outputting the content of the DOM editor of the page or section containing the link is not recommended, since this would result in an infinite loop (in Fig. 2: st_var_form, indicated by the dotted line). In general, it never makes sense to output external context to internal context. |
Thus, by default, values that the editor enters in a link (in Fig. 2: link_var_form) are only available in the context of the link. These values can also be made available in the next higher section or page context by using #global.context("NAME"):
$CMS_SET(#global.context("section")["link_var_form"],link_var_form)$or
$CMS_SET(#global.context("PAGE")["link_var_form"],link_var_form)$As with other FirstSpirit objects, variables in a link can be overwritten by using $CMS_SET(...)$. This applies both to variables used as identifiers for input components on the "Form" tab of the link template as well as for variables that are defined in a template set of the link template using $CMS_SET(...)$, for example. An example of applying this might be an auto completion or auto correction, e.g. for e-mail addresses (also refer to the example for e-mail links). In this case, a check is first made to determine if the editor entered an e-mail address with the required “mailto:” information in the lt_reference input component. For instance, if “mailto:” is missing, it is added automatically.
$CMS_IF(!lt_reference.startsWith("mailto:"))$
$CMS_SET(lt_reference, "mailto:"+lt_reference)$
$CMS_END_IF$Variables in the Global content area
Fig. 3: Structure of the Global content area
Content of a global page (and possibly of the sections integrated in the global page) is output in the desired template using $CMS_VALUE(#global.gca("IDENTIFIER"))$. For the IDENTIFIER placeholder, the reference name of the Global content area page to be output must be specified. The content of the corresponding template is inserted where the $CMS_VALUE(#global.gca("IDENTIFIER"))$ call is located, and the context of the global page is started. Contexts are also nested in this case.
Fig. 2 shows a simplified structure of a page with a section in the Page Store (“PS”) with a page and section from the Global content area (“GCA”). Even here you can find “external” elements (such as a page in the Page Store) and “internal” elements (e.g., the section in the Global content area).
Fig. 4: Contexts of the Global content area
This nesting makes it possible to overlap or overwrite the contexts of sections, since, for instance, the (PS) section and (GCA) section each have a context called section. The (PS) page and (GCA) page on the other hand each have their own context. In this case, only the context of the “innermost” section, and thus usually the section from the Global content area, is addressed using #global.context("section").
The ID and the reference name of the page or section from the Page Store or Global content area can be output using #global.page.id and #global.page.name or #global.page.uid or #global.section.id and #global.section.name respectively.
Variables defined in the page and section templates on which the (PS) and (GCA) pages or (PS) and (GCA) sections are based apply to the current page or section as well as to all internal elements by default. If a variable is also to be made available to the external elements, #global.context("PAGE") can be used for this purpose.
If variables with the same identifier are defined in the page and section templates, the variable of the current element is always used. This means that in every template, variables defined in this template can be accessed with familiar instructions (also refer to Variables in templates).
To ensure that the variables of the current element and other elements can be accessed via any of the templates for the page and sections from the Page Store and from the Global content area, unique variable identifiers should be selected in the templates.