Variables in FirstSpirit
| Contents |
In FirstSpirit,
- the content of a website (e.g. texts, pictures, structured data from databases) is managed separately from
- the structure (e.g. what does the sitemap look like? What is the hierarchy of the individual web pages?) and
- the display or layout (e.g. what colors are used for the web pages? How are the texts and pictures arranged on a page?),
and this management takes place in the so-called “Stores”. This concept fulfills the paradigm of separation of structure, content and layout of a website.
The content is saved as values in variables. In each store, there are options for
- defining variables (“Declaration”) and assigning values to variables (“Initialization”)
(see section below) - for relating variables to each other (including across stores) and for manipulating them (“Operation”)
(see section below) - for outputting the saved value again in the required place
(see section below)
In this way, the content entered by editors can be easily reused and dynamically output on the website (e.g. linked to specific conditions). Operations – depending on the content type – also allow template-based modification of the content entered by editors, i.e. once entered, (raw) data can be output in different forms on the website without additional work for the editor.
There are also additional variables, which are specified / maintained by the system. These are also called “system objects” and are identified by the # symbol in front of the variable name (e.g. #global). A description of these FirstSpirit system objects is given in the System objects chapter.
Syntax of variables
Each variable has a unique identifier and a changeable value. The value of a variable is accessed via the unique identifier. An identifier can consist of letters, numbers and underscores (_).
A valid variable identifier must:
- contain at least one letter (examples: a, a1, a_b) or
- start with an underscore and contain at least one letter or one number (examples: _0, _a).
(Examples of invalid variable identifiers: _, __, 12, 12a, a-1)
 |
Hyphens (-) are not permitted in the variable identifier! |
|
Variable identifiers should not be subsequently changed, as otherwise existing references in the project can become invalid, i.e. relations between objects are lost. |
A project-wide unique identifier should be assigned to each variable, as otherwise variables can “overwrite” each other. However, in several cases this can be desired. For further information, refer to the Contexts chapter.
Coding conventions
To obtain a better overview of the variables used in a project, it is advisable to integrate a variable prefix in the identifier, by which the definition location can be read. This also ensures that variables do not overwrite each other, e.g.
- gv_: Variable which is to be used globally in the project (e.g. gv_pagetitle)
- pt_: Variable which is defined in a page template (e.g. pt_pagetitle)
- st_: Variable which is defined in a section template (e.g. st_text_picture)
- ft_: Variable, which is defined in a formate template (including table style templates)
- lt_: Variable which is defined in a link template (e.g. lt_linktext)
- tt_: Variable which is defined in a table template (e.g. tt_date)
- sc_: Variable which is defined in a script
- md_: Variable which is defined in a metadata template (e.g. md_keywords)
- ps_: Variable which is defined in a project settings template (e.g. ps_copyright)
- gc_: Variable which is defined in templates for Global Content
- dv_: Variable which is only defined for a deployment target (Deployment value)
- ss_: Structure variable which is defined in the Site Store (Structure variables should principally be defined on the root node of the Site Store, e.g. ss_shownavigation)
- fr_: Variable storing the results of header function calls (a secondary prefix should be used to determine in which template the function result has been calculated, e.g fr_pt_mainNavigation)
- set_: Temporary variable which is defined in a CMS_SET instruction (another prefix should specify where the CMS_SET is called, e.g. set_st_teaserbox)
- for_: Indexed variable which is defined in a CMS_FOR instruction
There are also several reserved variable identifiers, e.g. for using functions (contentSelect, Navigation, MenuGroup, PageGroup, etc.), WebEdit, the so-called inline tables (see also system object #style), etc.
Where and how can variables be declared?
Variables can be declared in almost all places within the project. Where a variable is best declared is derived from the specific application case in the project (see also Template-related contexts chapter). How they are declared is described in detail in the relevant chapters, which are given in the following table.
Where? | Meaning and examples of usage |
|---|---|
in templates | The input components, the central control element for editors in FirstSpirit, are defined on the Form tab. The name attribute represents the variable name of an input component (see name attribute, e.g. in the input component CMS_INPUT_DOM). The value entered by the editor in the input component is stored in the variable defined using name. |
Analogously, variables can also be defined in template sets, using the instructions
The value is assigned by the project developer, editors do not have any access to these variables. | |
in the metadata | So-called metadata can be entered for each node in the Page, Mediate and Site Store and in the Global Store. This is additional information, which can be passed on (inherited) to lower-level nodes. They are entered via input components in a page template, which was defined accordingly via the project settings (server and project configuration application). Metadata can include comments, for example, as well as information about user permissions (using the input component CMS_INPUT_PERMISSION). |
at menu levels | Menu levels of the Site Store can be assigned variables. With these, it is possible to access sub-areas of the navigation, for example, to influence the layout. Structure variables can also be handed down to lower menu levels. For example, structure variables can be used to implement different designs (background, font color, buttons, logos, etc.) for different (hierarchical) areas of a website. |
in the Global Store | In the "Global Store", you can manage content which is to be frequently re-used. These may include text blocks (boilerplates), etc., which are used on each web page but are to be entered separately from other texts on a page, e.g. a copyright notice at the end of a page. If such a text block requires changes or updates, only that single text block has to be changed, but not each page that uses this text block. This content is entered via input components in a page template, which has been defined via the project settings (server and project configuration application) accordingly or page and section templates, which are used in the Global Content Area. |
in schedules | Variables can be set in the generation schedule, and they are read out when a project is generated. In this way, for example, variables, which were defined in the menu levels, can be overwritten. |
How can variables be manipulated?
You can use
to manipulate variables depending on their data type or to relate them to other variables.
Therefore, variables can only be manipulated on the template set tab of templates.
How can variables be output?
The values of variables can be output in template sets using the $CMS_VALUE(...)$ instruction. References are resolved to paths with the instruction $CMS_REF(...)$:
Output via $CMS_VALUE(...)$
The content or value of a variable can be output with the instruction $CMS_VALUE(...)$, where the identifier is included inside the parentheses.
Hello $CMS_VALUE(name.firstname)$ $CMS_VALUE(name.lastname)$!
Extended outputs can also be evaluated inside the parentheses.
Hello $CMS_VALUE(name.firstname + " " + name.lastname)$!
|
If a variable (in the example, name) is not defined or if it is zero, a corresponding error message is output in the log for debugging purposes, e.g. Undefined field or Undefined variable. To prevent these error messages, depending on the application case, an isNull- (.isNull() method) or isEmpty test (.isEmpty() method) can be performed, e.g. $CMS_IF(!name.isNull)$ $CMS_VALUE(name)$ $CMS_END_IF$ The possibilities of using the isSet(...) function – to check whether a variable is set or not – or using default to define a default value (e.g. $CMS_VALUE(name, default:"Default value")$, see $CMS_VALUE(...)$), should be used carefully, as in this case error messages are suppressed, which makes troubleshooting (“debugging”) difficult, and, in the case of isSet, there is a possibly unwanted output of the value on the generated page. |
More precise information on calling (invoking) variables via $CMS_VALUE(...)$ and several practical examples are given in the $CMS_VALUE(...)$ chapter.
Output via $CMS_REF(...)$
If the content of the variables follows the relevant rules, the variable invocation can also take place via the instruction $CMS_REF(...)$. If $CMS_REF(...)$ is used, the variable must always consist of two parts:
- a keyword (for example, media:) and
- a reference name from the respective store (with the keyword media:, for example, a reference name of a medium from the Media Store).
More precise information on calling (invoking) variables via $CMS_REF(...)$ and several practical examples are given in the $CMS_REF(...)$ chapter.