Variables

This chapter gives you a preview of all variables which can be used in templates.

Observe the order of the substitution of variables while parsing a document. Each variable is replaced with the corresponding content at a particular moment.

Since a document can be processed by more than one parser, there is a risk, when using inappropriate variables, that they have already been replaced with an earlier parser and cannot be found by the next one.

The replacement sequence of variables is as follows:

XX variables
 variables
TM variables (only SiteActive)
YY variables (only SiteActive)
FF and ZZ variables (only SiteActive)
MM variables
UU variables (only personalization)
GG variables (only SiteActive)

Variables are called in two different ways:

When there are multiple parameters allowed, use a colon-separated list. Example:

The following is a list of all variables used in imperia:

Detailed information are to be found in the section of each variables.

Note

The marked with an asterisk (*) variables in this list accept a colon syntax (see above).

CC variables
dirlevel variables *
ENV variables
FF variables (only SiteActive)
GG variables
KK variables
MEMBER_OF variables
MM variables
XX-mode variables
SECTION variables *
SECTION_DESCR variables (shortcut for SECTION:NAME)
SYSTEM_CONF variables *
TCOUNTER variables *
TM variables (only SiteActive)
TMDEF variables (also TMDEFINED)
USER_CONF variables *
XXOBJ variables
MEMBER_OF variables
UU variables (only personalization)
GG variables (only SiteActive)
Xdir variables *
Xdate variables *
Xtime variables *
XX variables
XX-DEF variables
YY variables (only SiteActive)
ZZ variables (only SiteActive)

`CC` variables#

Only the template processor of a develop system processes this type of variables. The functionality is similar to that of XX variables, with the difference that special characters are URL escaped. These variables are also an alias for XX-URI.

Every special character is replaced by a triplet in the form of %xx, where xx is the hexadecimal code of the corresponding sign.

CC variables are removed in the same way as XX variables, when the corresponding meta variable is not present.

`dirlevel` variables#

This variable type is only processed by the template processor of a target system. The dirlevel variable type delivers part of a document's path.

With the help of parameters, you can define which part of the path is delivered by the variable. Here is an example:

Let us assume that a document is under /sport/golf/pga-tour. The  variable contains the value sport, the  variable contains the value golf and the <--dirlevel:3--> variable contains the value pga-tour.

`FF` variables (only SiteActive)#

FF variables access the form variables of a SiteActive template. If it is in a SiteActive template of an imperia document, all meta information of the SiteActive templates is in FF variables.

The transfer parameters of a system service can also be called with FF variables.

Here is an example:

TEMPLATE=/site_active/template.html:SAVEPAGE=/save/page/index.html:dir=/sport

The  variable now contains the value /sport and is usable in a document. Example:

<IMPERIA>
  READDIR "<!--FF-dir-->"
</IMPERIA>

The dir variable from the system service's configuration serves for the placement of the READDIR in the SiteActive code.

The function is case sensitive. The variable foo is not the same as Foo. Furthermore, it is possible to extend or reduce FF variables during template or document processing:

<!--FF-name+number-->
<!--FF-name-number-->

If there is no form attribute with the corresponding name, the FF variable is expanded to an empty string. The expansion of FF variables is done before the processing of IF conditions, and therefore you can use FF variables within IF conditions.

`GG` variables#

This type of variables can only be used within SiteActives and for personalization. It provides the evaluations of <IMPERIA lang=perl> blocks in the provided template.
The syntax  is replaced by the name value of the %$GLOBAL hash.

The results of an <IMPERIA lang=perl> block can be stored with the help of the following syntax:

$GLOBAL->{Name}= computed value

Within a template you can use the  variable to access this stored value.

GG variables are not useful within IF conditions, since their expansion is done after IF conditions are evaluated. They can, however, be used in FOREACH FOUND.

`KK` variables#

This type of variables serves exclusively for input of meta information in the MetaEdit step. The entered meta information can be referenced at the end of this workflow step with KK variables.

When you, for example, define an input field name, you can access it through the  variable. The replacement is done when exiting the MetaEdit plug-in with save. The KK variable returns an empty string, if there is no such input field, or no user input for it.

Example:

A website is in multiple languages and there are four template variants available. A user selects one of them, which will also be used for the copy pages. The following code can be used in the meta file:

SELECTION "template:Please select a template"
        OPTION "tpl01:variant 1"
        OPTION "tpl02:variant 2"
        OPTION "tpl03:variant 3"
        OPTION "tpl04:variant 4"
ENDSEL

HIDDEN "copy1:<!--XX-directory-->/index_en.html:TEMPLATE=
        <!--KK-template-->_en"
HIDDEN "copy1:<!--XX-directory-->/index_fr.html:TEMPLATE=
HIDDEN "copy1:<!--XX-directory-->/index_de.html:TEMPLATE=
        <!--KK-template-->_de"

Note

The hidden instructions in the above code example are wrapped for representation purposes.

A user assigns a value to the variable with the select box. This variable can be read at the end of the MetaEdit step with . At this workflow step, only previously set variables can be reference with the XX variables. In the above example this is the directory name, accessed by .

Another example:

Instead of a template selection, you can also offer different select boxes for the category and the priority of an article. The name of the template to be used can be built from this information:

HIDDEN "template:<!--KK-category--><!--KK-prio-->"

Additionally you can declare "constants", in order to generate a link between the combination of category and priority and the template number:

HIDDEN "quotes01:0150"
HIDDEN "quotes02:0160"
HIDDEN "news01:0170"
HIDDEN "news02:0170"
HIDDEN "sports01:0150"
HIDDEN "sports02:0160"

The definition of the template to be used is performed as follows:

HIDDEN "template:<!--KK-<!--KK-category--><!--KK-urgent-->-->"

`MM` variables#

Just like YY variables, MM variables provide access to meta field content of a source document for SiteActive pages. However, the replacement of the MM variables is done before the replacement of the YY variables. For that reason, constructions as the following are possible in your SiteActives:

<!--YY-<!--MM-category--><!--MM-urgent-->-->

After the two MM variables are expanded, the result is the name of the YY variables, which will be used subsequently. A requirement is that a meta variable with the composite name exists.

`SECTION` variables#

With this type of variables you have access to the category information of the currently used template.

The syntax of a SECTION variable is as follows:

<!--SECTION:Parameter>

Possible parameters are:

DESCR
Returns the description of the category.

NAME
Returns the name of the category.

DIRECTORY
Returns the standard directory of the category

TEMPLATE
Returns the standard template of the category.

FILENAME
Returns the standard filename of the category.

META_INFO_meta field name, resp. meta field name
Returns the meta information from the metafield name field.

The setting of this parameter can be done in the category administration. However, you can allow for these values to be overwritten via a workflow plug-in or user input in the meta file or the template.

In addition, you can also read data from a parent category. In this case, the desired category's level has to be given as a second parameter. To access a top level category, use the value 1. For example, you can read the description of a top level category using the following syntax:

<!--SECTION:DESCR:1-->

For compatibility reasons the  syntax may also be used, but this is not recommended.

Access To Categories' Meta Information#

As described in Editing Categories in the administration documentation, categories may also be provided with meta information. This information is selectable in all of a category's documents, as well as its subcategories. The syntax is as follows:

<!--SECTION:META_INFO_meta_field_name-->

<!--SECTION:meta_field_name-->

<!--SECTION:meta_field_name[index]-->

The prefix META_INFO_ is optional and serves only for better diversification of internally valid document meta variables. If the corresponding meta field contains an array, the index of the desired element from the array has to be indicated after the meta field name.

`SYSTEM_CONF` variables#

With the help of this type of variables you can query all defined in /site/config/system.conf system settings. The syntax is as follows:

<!--SYSTEM_CONF:Parameter-->

Important

The old imperia syntax with minus sign instead of the underscore is not supported anymore.

The placeholder parameter stands for an arbitrary configuration variable from the /site/config/system.conf file. If the desired variable is defined, imperia returns its value, otherwise you get an empty string.

Practically all settings from /site/config/system.conf can be called. For a list of the available system configuration variables see in chapter System Configuration Variables of the administration documentation.

You may use escaping with this variable type (see Escaping Modes).

`TCOUNTER` Variables#

This type of variables is only available on the develop system for simple arithmetical calculation operations. The syntax is as follows:

<!--TCOUNTER:Meta Variable Operator Value-->

The expansion of TCOUNTER variables takes place before the expansion of XX variables. That allows constructs like the following:

<!--XX-text<!--TCOUNTER:an+1-->-->

`TM` variables (only SiteActive)#

TM variables are used to access the meta information of SiteActive templates. Variables of this type deliver an empty string when the corresponding meta variable doesn't exists.

Important

TM variables can only be used with SiteActive templates that are stored as documents in imperia.

Here is an example:

Let's assume that when generating a SiteActive template with imperia, the directory is saved in the meta variable dir.

Now, the following is possible:

<IMPERIA>
  READDIR "<!--TM-dir-->"
  ...
</IMPERIA>

During the processing of this imperia blocks, the  variable is replaced with the directory, indicated in the SiteActive template in dir. When the SiteActive executes the imperia block, it searches in the defined directory and its child directories. If, however, the dir variable is not defined, an empty string is returned and no directories are searched by the SiteActive.

Alternatively, the SiteActive template can be published directly in the directory to be searched. In this case, simply define  as READDIR.

`TMDEF` variables#

This type of variables are only available in imperia maintained SiteActive templates and return true (numbers) or false (number 0) values. The TMDEF return true if the desired meta variable exists in the SiteActive template and it is not empty. In this case, the query returns the number of characters contained in the meta field. In any other case, TMDEF returns false (number 0).

This variable type can be used to check if a field is empty or does not exist.

Example:

FOREACH FOUND {
        <div class="inner">
                IF "<!--TMDEF-category-->" PRINT <!--TM-category-->:
                <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
                <br />
                <span class="ant"><!--YY-headline_0_0--> =>> mehr</span>
        </div>
}

The code above displays the category name of the SiteAcive, if defined, before the elements list.

`USER_CONF` Variables#

Data stored in the user management for the currently logged in user can be read out with the help of this variable type. The currently logged in user is not necessarily the creator of a document but the user who currently edits it.

The syntax for these variables is as fallows:

<!--USER_CONF:value-->

Important

The old imperia syntax with minus sign instead of underscore is not valid anymore.

You can check for the following values:

User Management fields
variable	description
homepage	homepage
country	country
telnumber	telephone number
language	language
cellular	cellular
name	name
fname	first name
city	city
faxnumber	fax number
comment	comment
zip	zip
login	login ID/login
email	email address
street	street

You may use escaping with this variable type (see Escaping Modes).

`Xdir` Variables#

This variable type is only valid because of compatibility reasons with previous imperia versions. Its use is not recommended. Instead use dirlevel (see dirlevel variables).

`Xdate` Variables#

This variable type provides variety of date formats. The syntax is as follows:

<!--Xdate:format-->

The following are valid date formats for this variable type:

Date parameters
format name	readout
default	15.08.2001
full	15.08.2001
inverse	2001-08-15
afiles	2001-08-15 22:13
iso	20010815
normal	15.08.2001
american	15.08.2001
imperia	15.08.2001 22:03
finddate	2001.08.15 22:03

`Xtime` Variables#

This variable type provides variety of time formats. The syntax is as follows:

<!--Xtime:format-->

The following are valid time formats for this variable type:

Time formats
format	readout
default	22:14
normal	22:14:18
full	22:14:18
compact	22:14
hour	22
minute	14
second	18

`XX` variables and `XXOBJ` Variables#

These variables can be processed both in MetaEdit and in the Edit steps of a workflow. The tags are always replaced. This means that an expression in the form of  does not remain in this form in the generated HTML code of a document. It either produces the content of the corresponding meta field or an empty string, when the corresponding meta variable is not existing or is not set.

XX variables can also be used within <IMPERIA></IMPERIA> blocks. This is possible only when the SiteActive template is an imperia document. In this case, the variables are only replaced when there is an existing meta variable, if not, the expression is left unchanged and is displayed in the finished HTML page.

With  you can call all meta information available in a document. As long as you store a document, even in document preview, the XX variables are replaced by the value of the corresponding meta variable. If the corresponding meta variable contains a list of values, you can indicate the index of the desired elements after the meta field name: .

If the required meta information comes from an object in the Media Asset Management or the image upload, instead of  you must use the tag . imperia will then insert the path to the corresponding media file both in PREVIEW and SAVE mode of a document.

Modifiers for `XX` variables#

If the referenced meta fields originate from a flex module, imperia block or array block, you must add a modifier before the meta field name, in order to mark it. This is done with the following syntax:

<!--XX-MODIFIER-meta_field_name-->

The following modifiers are recognized by imperia:

Modifiers for `XX` variables
Modifier	Meaning
`SLOT`	Modifier for slot module contents.
`FLEX`	Modifier for flex module contents.
`IBLOCK`	Modifier for imperia block contents.
`ARRAY`	Modifier for array block contents.

Using the modifier, imperia supplements the meta field name with the corresponding index and ID. However, this applies only if access takes place within the element in question. If you wish, for example, to have access to contents in a template outside a flex module, you must attach the flex index and flex id of the corresponding module to the meta field name. Refer to Using Content Outside Flex Modules.

`XX-DEF` Variables#

This variable type is processed both by the MetaEdit and the Edit plug-ins and returns 1 or 0. XX-DEF variables return 1, when the corresponding meta variable exists and is not empty. Otherwise, the variable returns 0. XX-DEF variables are used in order to test if a meta variable exists, resp. is not empty.

Note

Quotation marks for XX-DEF are not necessary in IF conditions in a template.

For more informationen, refer to the Perldoc in Meta::Info and Meta::Base class (IWL::Stash in imperia 8 ).

perldoc site/modules/core/Meta/Info.pm 
perldoc site/modules/core/Meta/Base.pm

`XX-mode` Variables#

The XX-mode variables store the mode of a document. The following values are possible:

EDIT
SAVE
PREVIEW
REPARSE

For more information refer also to Querying and Testing a Mode.

`YY` variables (only SiteActive)#

These variables are used in the FOREACH FOUND loops in SiteActive templates. In this way you can have access to the meta information of found documents.

Example:

Let's assume that the index.html file is in the /sport/sailing/00333 directory. In order to obtain a link to this site in a SiteActive, the following code has to be entered in the FOREACH FOUND loop:

<a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>

For every found document the / is replaced with its directory path during the SiteActive run, so that at the end in the generated document contains a valid link, starting from the document root. The link text is built by replacing the  with the document's title.

Within a FOREACH FOUND loop,  gives access to every meta variable of a found document.

For YY variables, similarly to the way this is done in templates, you can specify whether and how the content of the variables should be escaped. For this purpose, the YY is called as follows:

<!--YY-TEXT:meta_variable_name-->

With this syntax the content of the referenced meta variable is escaped, so that, for example, the character "<" is displayed as "<".

Additionally you can specify which characters should be escaped and which not. For this purpose, the YY is called as follows:

<!--YY-TEXT:(':"):meta_variable_name-->

The signs which should be escaped, are written in a colon-separated list in round brackets. In the example above ' and " are escaped. Instead of the actual characters you may also use ASCII codes:

<!--YY-TEXT:(34:39):meta_variable_name-->

Example:

The content of the referenced meta variable test is ">, <, ", &". The FOREACH FOUND loop in a SiteActive template is as follows:

FOREACH FOUND {
  <tr>
    <td><!--YY-test--></td>
    <td><!--YY-TEXT:test--></td>
    <td><!--YY-TEXT(<:>):test--></td>
  </tr>
}

The generated by the SiteActive HTML page contains only the following:

<tr>
  <td>>, <, ", &</td>
  <td>&gt;, &lt;, &quot;, &amp;</td>
  <td>&#62;, &#60;, ", &</td>
</tr>

`ZZ` Variables (only SiteActive)#

ZZ variables offer access to the date and time.

By default, these variables provide the time and date in Greenwich Mean Time (GMT). A correct comparison with the time variables which provide local time is not possible. For comparison, use XstrftimeGMT.

In addition, simple calculations are also possible. The syntax of a ZZ variable is as follows:


<!--ZZ-format-->

The following formats can be used:

day

Returns the current day of the month as a number.

mon

Returns the current month as a number with leading zeros for one digit months. Example: 08 for August.

month/fullmonth

Returns the current month as text.

fullyear

Returns the current year as a four digit number.

shortyear

Returns the current year as a two digit number.

year

Returns the number of years since 1900. This format should be used only for calculations.

time

Returns the time in HH:MM format.

longtime

Returns the time in HH:MM:SS format.

hour

Returns the current hour.

min

Returns the current minutes.

sec

Returns the current seconds.

dayofweek

Returns the day of the week as text.

Field (+|-) unit

With this format you can add or subtract a unit of one of the above mentioned formats. Example:

<!--ZZ-time+58MINS-->

In this example 58 minutes are added to the current time.

Possible units are:

Units
unit	description
SECS	seconds
MINS	minutes
HOURS	hours
DAYS	days
WEEKS	weeks
MONTHS	months
YEARS	years

Escaping Modes#

After the content from a variable is referenced, it can be modified with escaping modes. They do not completely change the meta information itself but only its output representation.

Note

The default escaping mode is RAW.

When you use escaping, imperia first checks if under site/modules/core/Dynamic/Escape/ there is a corresponding plug-in (for example JS.pm). If yes, the plug-in is used, if not - one of the fixed modes is used. These are:

RAW
HTML
HTMLBR
TEXT
TEXTBR
META
FILESIZE
JS
URI

Some modes (currently TEXT, TEXTBR and FILESIZE) can be called with arguments, e.g.:

<!--XX-TEXT(':":60:38):attrib-->

RAW (Default Mode)#

Entered HTML code is not escaped and it also changes the layout of the finished HTML page.
Stored linebreaks are not displayed.

HTML#

This mode is implemented for compatibility reasons with imperia 6. It has the same properties as the RAW mode.

HTMLBR#

Entered HTML code is not escaped and it also changes the layout of the finished HTML page.
Stored linebreaks are transformed into <br> tags and displayed in the finished HTML page.

TEXT#

Entered HTML code is escaped.
Stored linebreaks are not displayed.

<!--XX-TEXT(':":60:38):attrib-->

In this example, the meta field “attrib” is to be displayed with single and double quotes, and characters with codes 60 (less-than sign) and 38 (ampersand) are replaced with the corresponding HTML entities.

If no arguments are given when calling TEXT, single and double quotes, less-than, greater-than and ampersand are replaced with the corresponding HTML entities.

TEXTBR#

Entered HTML code is escaped.
Stored linebreaks are transformed into <br> tags and displayed in the finished HTML page.

<!--XX-TEXTBR(':"):title-->

In this example, the meta field “title” is to be displayed and single and double quotes are replaced with the corresponding HTML entities.

If no arguments are given when calling TEXTBR, single and double quotes, less-than, greater-than and ampersand are replaced with the corresponding HTML entities.

FILESIZE#

This escaping mode converts file sizes available as simple number, in human-readable formats like 7 kB or 3.5 GB.

<!--XX-FILESIZE(digits=1 lingua=de no_si=1):filesize-->

The parameters have the following specific meanings:

digits: Number of desired positions after the command. Default is 1.
lingua: It indicates in which language format the result should be formatted. This concerns the decimal point.
no_si: By default FILESIZE calculates using SI units, this means 1 kilobyte (kB) = 1.000 byte. By setting the parameter no_si to a nonzero value, the conversion is done in binary, this means 1 kilobyte (kB) = 1.024 byte.

JS (JavaScript string)#

Entered code is escaped so that it can safely be transferred to a JavaScript string.
Stored linebreaks are displayed as \n.

<script type="text/javascript">
    var input="<!--XX-JS:input-->";
    alert(input);
</script>

URI#

Entered text is based on the MIME type application/x-www-form-urlencoded. Example:

entered text: this should be <b>printed </b>-bold.
readout text: this%20should%20%3cb%3ebe%3c%2fb%3e%2dprinted%20bold

Important

The described here modes are not to be confused with the modes for programming input fields and text areas in a template. If an input field or a text area are given an invalid mode in a template, the resulting meta variable's content won't be accessible. Refer to the instructions in Textarea.

Variables

CC variables#

dirlevel variables#

FF variables (only SiteActive)#

GG variables#

KK variables#

MM variables#

SECTION variables#

Access To Categories' Meta Information#

SYSTEM_CONF variables#

TCOUNTER Variables#

TM variables (only SiteActive)#

TMDEF variables#

USER_CONF Variables#

Xdir Variables#

Xdate Variables#

Xtime Variables#

XX variables and XXOBJ Variables#

Modifiers for XX variables#

XX-DEF Variables#

XX-mode Variables#

YY variables (only SiteActive)#

ZZ Variables (only SiteActive)#

Escaping Modes#

RAW (Default Mode)#

HTML#

HTMLBR#

TEXT#

TEXTBR#

FILESIZE#

JS (JavaScript string)#

URI#

`CC` variables#

`dirlevel` variables#

`FF` variables (only SiteActive)#

`GG` variables#

`KK` variables#

`MM` variables#

`SECTION` variables#

`SYSTEM_CONF` variables#

`TCOUNTER` Variables#

`TM` variables (only SiteActive)#

`TMDEF` variables#

`USER_CONF` Variables#

`Xdir` Variables#

`Xdate` Variables#

`Xtime` Variables#

`XX` variables and `XXOBJ` Variables#

Modifiers for `XX` variables#

`XX-DEF` Variables#

`XX-mode` Variables#

`YY` variables (only SiteActive)#

`ZZ` Variables (only SiteActive)#