Templates

One of the tasks of a Content Management System is to make it possible for authors to enter content for a web site without the necessity of HTML or programming knowledge.

To implement this, not only an input mask should be prepared for the content, but the entered content must be integrated in the existing layout of the site, too.

The tool for performing these two tasks in imperia is templates. The literal meaning of the term “template” is quite accurate. It includes fixed and flexible elements. In this way you can guarantee that a unified base layout remains unchanged while the content is changeable. Thus, with a template you specify the following:

Size, position and type of images
Appearance and position of the text
Size, position and appearance of the navigation
General design of a document (logo, background images and colors etc.)

The author can concentrate on the text input and resp. the selection of images to illustrate it.

Technically seen, a template is an HTML file with form fields for text input or the HTML skeleton for the final page.

The input of content and its output into a layout can be done with a single template or with two separate templates:

With the first variant, the authors work with the look-and-feel of a WYSIWYG application. Instead of the input elements, the final page contains the formatted content. In this way users have a clear idea about what the published document will look like even at the editing phase.
If you want to present the entered content in multiple layouts, the second variant is recommended: a layout-neutral structure of the input template and specifically designed publishing template for the presentation of the entered content, see following figure:

Which template is used at which location in a workflow is decided in the settings of the corresponding category or even in the workflow itself. From administrative point of view, there is no difference between input and output template in the administration of templates.

Which elements of a site are preset and which elements can be added or processed by an author is determined by a template developer. Except for the already mentioned text input fields, you can give the user the possibility to choose images and place them at various locations in an article. Optionally, you can integrate external applications, too, for example, external code such as PHP, JSP, etc.

imperia also allows you to give even more freedom about the content's presentation to the user. Additionally, you can provide different combinations of structure elements, allowing authors to be more flexible.

Templates do not only take the content for a document, but they also show you the possibility for implementing other functions:

Filling in variables
Evaluating variables
Inserting images and other media
Executing Perl code

Upon completion, the document leaves its workflow. In this moment, imperia's template processor inserts the content collected in the course of the workflow into the output template and creates a file from it. This file can then be published to the target system(s).

Conventions for Filenames and Keywords#

The following conventions for filenames and keywords are used in imperia:

filenames

The filename of a template is arbitrary, but it must not contain any special characters except for an underscore or hyphen. The filename prefix template known from older imperia versions prefix is no longer necessary. Save your template with the file extender .htms.

Volatile meta variable names

imperia modifies meta variable names in flex modules and imperia blocks by appending the corresponding indexes, separated by underscores to the meta variable name. Therefore, you should avoid meta variable names in the form of name_1_2_3, if you use flex modules or imperia blocks that can contain such meta variables (name). This can result in overlaps and data loss.

The following names are reserved as keywords and should not be used as meta variable names or if used, this should only be done in a limited way:

__imperia, _washed

Keywords that start with __imperia and _washed pass internal parameters between the different layers of imperia and the browser.

copy

Keywords that start with copy, are reserved for copy pages.

directory, filename, template, author

These keywords are used by the publisher and the workflow engine.

publish_date, expiry_date, no_publish, __publish_..., __expiry...

These keywords pass parameters to the publisher.

title

This key can be used with limitations. It is used on the desktop in imperia among others as the document's title.

language, languages

These keys are used by the localization module.

imperiaflex, imperiablocks

These keywords are prefixed with anonymous meta variables from flex modules and imperia blocks.

Template Fundamentals#

A template can operate in different modes:

EDIT
PREVIEW
REPARSE
SAVE

The various modes can be queried with the help of variables. This makes it possible to hide some template elements, resp. display them in the different modes. A good example for this is hiding particular elements (hints, etc.) in PREVIEW mode, so that the preview corresponds to the final document.

Templates are linked to categories just as meta files and workflows. You can learn more about categories and workflows configuration in the administration manual, meta files are covered in Meta Files.

All data entered into a template can be queried with variables and used elsewhere in a template. Therefore, you must ensure unique names for all input fields within a template.

The meta variable template determines which template serves as default for a document. This variable receives its value from the category settings. During the course of the workflow associated with this category, the meta variable can be changed using workflow plug-ins. Refer to Template Selection.

Allowed Characters in Variable Names#

Variable names in imperia may only contain the following characters:

digits
letters
underscores

Important

Colons cannot be used in variable names, since this leads to unexpected behavior. If you use a colon in a variable name while programming a template, for example: name="IMPERIA:txt:myname", the name of the variable is txt:myname instead of myname. The preview of the document seems correct, but you will not be able to access the content of the meta variable neither via  nor via .

Scripts, Forms, Frames and Layer/ILayer in Templates#

By default, scripts, frames and forms contained in a template are disabled in EDIT mode. This behavior can, however, be changed system-wide. Refer to chapter The Template Processor in this documentation or Template Processor of the administration documentation.

Favico.ico#

The favico.ico is used to define an icon to be displayed in the address bar of a browser. Bare in mind that if the favico.ico is not set, there will be an entry in the error log.

Syntax Reference#

The following section contains explanations of the template syntax. imperia expects relevant code between the formstart and the formend comments (see also Template's Body).

Content input in imperia is part of an HTML form. Users enter content via form elements which, then, is stored in variables. The variable names correspond to the name of the form element.

Such variables can be queried everywhere, using a special syntax (see Referencing Meta Variables).

Besides form elements, already known from normal HTML forms like <input> or <textarea>, imperia offers a number of proprietary tags for special and complex functions. Part of this are, for example, flex modules, imperia blocks, Media Asset Management invocations, etc.

In order for imperia to be able to categorize an HTML form element as relevant, you must extend the name attribute of this element as follows:

<input name="IMPERIA:variable name" type="text" size="35" />

Functions and constants in templates are described in Functions and Constants in Templates. For more information on managing templates in imperia, see chapter Templates in the administration documentation.

Template's Body#

Templates can be generated with an arbitrary editor. You should insert the following elements in order to generate an imperia template from one HTML file:

<html>
 <head>
  <title>Empty Template</title>
 </head>      
 <body>
  <!--formstart-->
   <!--template-description:Test template-->     
   <!--controls-->
  <!--formend-->
 </body>
</html>

In Edit mode, imperia replaces the line  with a form tag that has the corresponding attributes. This opens the form that is used to enter content into a template when generating a document. All input elements of the template must be placed within this form. If you omit the comment, the template processor inserts the opening form tag immediately after opening the body tag of an HTML document.
You can specify a template's description with . This description is displayed in imperia dialogs, for example, in the category settings.
In edit mode,  is replaced by the Cancel, Preview and Save buttons. If you want to position these three buttons in the header, footer or in the middle of a template, use this element at the desired place in the source code.  can be used multiple times within a template.
With the line , you insert the closing form tag in edit mode. When you omit this comment, the template processor inserts the closing form tag immediately in front of the closing body tag of an HTML document.

Note

The template body elements are no longer visible in the final document. The template processor removes the comments when the document exits its workflow.

You have to store template files in the directory /site/templates with the filename extender .htms.

HTML Escaping Modes#

Escaping modes are used to specify how HTML code, entered by a user, is displayed in the final documents. In general, the entered HTML code is never changed when storing it in the corresponding meta variable. The escaping mode determines whether the code be functioning HTML or simply displayed as text.

You can specify escaping modes for the following input elements:

input field
textarea

In a finished document the input elements of a template are replaced with the content of the corresponding meta variable. In this respect escaping modes could disturb the layout of a page.

You can also specify an escaping mode when referencing a meta variable (XX syntax). More information in Escaping Modes.

Important

If an input element has an invalid mode, for example, name="IMPERIA:TEXT:text1", the name of the variable resulting from this is not text1, but TEXT:text1! You will not be able to access the content of the meta variable neither with  nor with .

The escaping mode is appended as a parameter to the name attribute of the corresponding tag. The following example demonstrates it:

<input name="IMPERIA:HTML:Name" type="text" size="30" />

In the example, the possibly entered HTML code is taken into account and it changes the layout of the finished document. This can be desired (bold or italic markup), but it also poses a risk if a user enters complex layout changes.

The following escaping modes are available:

no mode

This is the standard mode of input elements. In this mode, line breaks are stored as new lines (\n). In the final document, these new lines are automatically transformed into tags.

The entered HTML code is escaped. For example,  becomes  in the final document.

HTML mode

This mode can be used in all relevant input elements. In this mode, the entered HTML code is not escaped and it influences the layout of the final document. Line breaks are not stored in the corresponding meta variable and are not displayed in the final document.

HTMLBR mode

This mode can be used only with textarea. It behaves like the HTML escaping mode, but line breaks are automatically transformed into   tags when displaying the content of the meta variable in the final document.

TEXT mode

In this mode all special characters are replaced by SGML entities.

TEXTBR mode

The is analogous to the TEXT mode, but all line breaks are replaced by .

URI mode

This mode converts special characters into percent characters, according to the convention necessary for the MIME type “application/x-www-form-urlencoded”.

Input Field#

Input fields are used in order to enter single-line text, for example article titles or image annotations.

The syntax for an input field can be extended with an escaping mode, in order to treat entered HTML code in different ways. Refer to HTML Escaping Modes

The syntax for an input field without escaping mode is as follows:

<input name="IMPERIA:Name" type="text" size="30" />

The syntax for an input field with escaping mode is as follows:


<input name="IMPERIA:Mode:Name" type="text" size="30" />

The default escaping mode is TEXTBR, so that would be assumed if no escaping mode is defined.

Textarea#

Textareas are used in order to enter multi-line text.

The syntax of a textarea can be extended with an escaping mode in order to treat the entered HTML code in different ways. Refer to HTML Escaping Modes.

The syntax for a textarea field without escaping mode is as follows:

<textarea name="IMPERIA:Name" rows="5" cols="40"></textarea>

The syntax for a textarea field with escaping mode is as follows:

<textarea name="IMPERIA:mode:name" rows="5" cols="40"></textarea>

The default escaping mode is TEXTBR, so that would be assumed if no escaping mode is defined.

Hyperlinks#

The syntax for a hyperlink is as follows:

<a href="IMPERIA:name">link text</a>

An input field for entering the URI of the hyperlink's target is displayed in Edit mode. To enable entering a link text, use the following syntax:

<a href="IMPERIA:link">
  #IF <!--XX-editmode-->
    Link text:
  #ENDIF
  <input name="IMPERIA:linktext">
</a>

Combo Box#

Combo boxes provide users the possibility to select one of multiple options. The syntax for a combo box is as follows:

<select name="IMPERIA:combo">
    <option value="option1">first option</option>
    <option value="option2">second option</option>
</select>

Tip

Unlike earlier imperia versions, the code must no longer be written in one line.

The template contains a combo box, in which only one option can be selected. The selected option is displayed in the final document. This allows you to modify the displayed texts, without having to change the meta variable.

In order to have one of the options as a default value, use the following syntax:

<option value="option1" selected="selected">first option</option>

MultiSelect Elements#

MultiSelect fields give users the opportunity to select multiple options from a list. The syntax is as follows:

<select name="IMPERIA:name" size="4" multiple="multiple">
    <option value="value">label</option>
</select>

The values selected in the multiSelect element are stored in an array. The numbering of the array elements starts with 0. Every array element can be referenced with bracket syntax. The bracket contains the position of the desired array instance.

Example:

<select name="IMPERIA:multiselect" size="4" multiple="multiple">
  <option value="1">1. option</option>
  <option value="2">2. option</option>
  <option value="3">3. option</option>
  <option value="4">4. option</option>
  <option value="5">5. option</option>
  <option value="6">6. option</option>
  <option value="7">7. option</option>
</select&gt;

In order to get, for example, the value of the second selected option, you can use the following syntax:

<!--XX-multiselect[1]-->

Refer also to Array Blocks.

Checkbox#

The syntax of a checkbox is as follows:

<input name="IMPERIA:name" type="checkbox" value="value">

It is possible to combine multiple checkboxes in a group. This is done via the name attribute (see the example).

Example:

<input name="IMPERIA:check3" type="checkbox" value="one" />
<input name="IMPERIA:check3" type="checkbox" value="two" />
<input name="IMPERIA:check3" type="checkbox" value="three" />
<input name="IMPERIA:check3" type="checkbox" value="four" />

If multiple checkboxes of a group are selected, imperia stores the corresponding values in an array, and it can be referenced with bracket syntax. In order to reference, for example, the third selected value from the example, you can use the following syntax:

<!--XX-check3[2]-->

Refer also to Array Blocks.

Radio Buttons#

The syntax for a radio button is as follows:


<input name="IMPERIA:name" type="radio" value="value" checked="checked" />

The attribute checked="checked" determines whether an options is selected by default.

Example:

<input name="IMPERIA:radio1" type="radio" value="one" />
<input name="IMPERIA:radio1" type="radio" value="two" checked="checked" />
<input name="IMPERIA:radio1" type="radio" value="three" />

File Upload (Media Asset Management)#

In order to create a template for assets upload into the Media Asset Management, you need a special input field for selecting the desired file for upload. This field can be generated in a template with the following comment:

<!--upload_start-->
<!--upload_end-->

Note

Currently the template processor ignores text between the start and end comment. HTML tags between both comments prevent the display of the upload field.

The workflow plug-in Upload interprets this comment and generates the following input element:

Input element for asset upload

imperia stores the selected file, as well as other information generated with input fields in the template, in the asset document.

Note

When you use a MAM template for multiupload, avoid using slot modules, flex modules and imperia blocks, since their use causes errors.

Flash Multiupload (Media Asset Management)#

You can use processing instructions to link the controls for flash upload in a template. The processing instructions' parameters configure the flash upload.
  is not necessary. The generation of meta information for the various assets via a template is unfortunately not possible.

Further information about the use of flash multiupload can be found in chapter Multiupload (flash) of the administration documentation.

<?imperia swf_upload?>

This PI is mandatory in order to be able to use the flash upload. The following parameter are available:

multiple:

Boolean value (default: 1). Set this parameter in order to activate the selection of multiple files in the file selection dialog.
autoUpload:

Boolean value (default: 0). Set this parameter in order to automatically start the upload process after a user closes the file selection dialog.
fileTypes:

String (default: ''). With this parameter you can limit the selection of uploadable files to a particular media type. The syntax is as follows:
```
fileTypes:extender01;extender02;extenderNN,Filtername
```
Example:
```
fileTypes: *.png;*.jpeg;*.gif;*.jpg,images
```
If this filter is set, a user can select only these file types in the “filetype” field of the file selection dialog.
fileSizeLimit:

Character string (default: '1024'). Enter a limit for the file size. Unless otherwise specified, the value is automatically interpreted as kilobytes. Set the parameter to 0, in order to allow size unlimited upload.

Examples:

123412, 4621B, 7962kb, 12MB, 2GB
fileUploadLimit:

Integer (default: 0). With this parameter you specify the maximum number of successful uploads for every cycle. The default, 0, allows the execution of as many successful uploads for every cycle, as needed.
fileQueueLimit:

Integer (default: 0). This parameter defines the highest number of files, which can be placed in the upload queue.
id:

String (default: random characters). This parameter serves as connection to a download queue. Refer also to the explanation of the bindToUpload parameter of the processing instruction <?imperia swf_upload_queue?> (see below).

<?imperia swf_upload_queue?>

This PI generates a graphical queue in a template for the upload of the selected files. The user can see the upload process and interact with it. The configuration of the queue can be done with the following parameters:

bindToUpload:

String (default: ''). Mandatory parameter. Enter the ID of the flash upload, that should be bound to the queue. This ID is included in the parameter id of the processing instruction <?imperia swf_upload?>. Without the parameter the display of the queue is not possible.
showHeader:

Boolean value (default: 1). With this parameter you can turn the display of column headers in the upload queue on and off.
order:

String (default: 'name,status,remove,conflicts'). Enter the column headers of the upload queue as a comma-separated string in the order you want them to be displayed. The string must not contain spaces! The following columns are available:
- name:
  
  The name of the uploaded file. Click on it in order to enter a new name.
- status:
  
  Shows a progress bar for the corresponding upload status.
- start:
  
  Displays a button that explicitly triggers the upload of the corresponding file.
- stop:
  
  Displays a button for canceling a running upload process.
- remove:
  
  Displays a button for interrupting a running upload and removal from the queue.
- conflicts:
  
  Displays a column for conflict test result. If a file with the same name already exists, this is noted in the column.
  
  This parameter is necessary for the order parameter! If it is missing, the flash upload is not functioning.

If multiple parameters must be assigned for swf_upload_queue, they have to be distributed to single cells, for example, in the following manner:

<?imperia swf_upload_queue
bindToUpload: multi
order: name,conflicts
?>

Images' Aspect Ratio#

MAM calls for images now accept comparison operators that affect the aspect ratio of an image. Instead of

width="500"

you can now alternatively specify

width="<500"
width=">500"
width="<=500"
width=">=500"
width="=500"

or even

width="lt500"
width="gt500"
width="le500"
width="ge500"
width="eq500"

in order for the syntax highlighting of your text editor to work:

The above settings define the minimum dimensions of an image. The image will not be scaled, when it already meets the requirements.

Frequent usage:

Scale an image — keeping the aspect ratio — so that it fits into a 640x480 pixels rectangle:
width="<=640" height="<=480"
Scale an image — keeping its aspect ration — so that it has a width of 640 pixels:
width="<=640"
Scale an image — keeping its aspect ration — so that it has a height of 480 pixels:
height="<=480"

Some more examples:

Scale an image — not keeping the aspect ratio — so that it has a height of 480 pixels:
width="<=640" height="=480"
Scale an image — not keeping the aspect ratio — so that it has a width of 640 pixels:
width="=640" height="<=480"

These settings produce undefined results:

width="<=640" height=">=480"
width=">=640" height="<=480"

Array Blocks#

Array blocks define one or more template modules as a matrix. The values which are entered in these modules, are stored as elements of the array block. Contrary to imperia blocks and flex modules, an array block does not generate a new name space. Because of this the meta variable names used in an array block must not be used for other meta variables in a template.

If an index for the array block is set manually with the parameter INDEX, it must be set manually for all other array blocks in a template. A mixture of automatically and manually assigned array blocks indexes must be avoided.

If no parameter to determine the length an array is set ( LENGTH or KEY), all referenced meta variables are tested in order to find the number of instances of an array block that have to be displayed. In this case, the instance number of the meta variable with the longest array is taken for all other array blocks. Under certain cirumstances this can result in some problems. That is why we recommend using a parameter for specifying the instance number, either KEY or LENGTH. Refer also to the further description of this parameter below.

The syntax for an array block is as follows:

<!--ARRAYBLOCK-->
  arbitrary HTML code
<!--/ARRAYBLOCK-->

Parameters are passed in the opening array block tag:

Example:

<!--ARRAYBLOCK:INDEX=4:LENGTH=3-->
   <input name="IMPERIA:array_text" type="text" size="30" value="" />
<!--/ARRAYBLOCK-->

The parameters passed here, determine the index of the array block (INDEX=4), as well as the maximum length of the array (LENGTH=3).

The following parameters are available:

INDEX=N

This parameter sets the index of an array block.

LENGTH=N

This parameter determines the maximum number of array instances.

KEY=Meta variable

With the KEY parameter, you can specify the length of all elements within an array block.

The following "comment elements" are available in array blocks:

ARRAY_INDEX

This variable contains the index of the current array block in a template, starting at 0, unless you have passed a fixed index in the parameter INDEX.

ARRAY_POSITION

This variable contains the position of the instance within the array block starting at 0.

ARRAY_POSITIONN

This variable contains, similar to ARRAY_POSITION, the position of the instance, but it adds the decimal value N to it.

XX-ARRAY-textfield

This variable contains the value of the textfield meta variable of the array block at the current position.

Example:

<!--ARRAYBLOCK-->
  Text:
  <input name="IMPERIA:text" type="text" size="30" value="" /><br />
  URL:
  <input name="IMPERIA:url" type="text" size="30" value="" /><br />
<!--/ARRAYBLOCK-->

The example code generates an array block with two input fields. Each one of them contains its own array. Using the buttons, a user can generate many instances, which are placed below the original instance.

Access to Array Instances#

Outside the array block, its data can be referenced with bracket syntax. The bracket contains the position of the desired array instance. The numeration of the array elements starts at 0. The corresponding syntax is as follows:

<!--XX-meta variable name[instance position]-->

example:

<!--ARRAYBLOCK:LENGTH=3-->
   <input name="IMPERIA:text" type="text" size="30" value="" />
<!--/ARRAYBLOCK-->

Reference: <!--XX-text[2]--><br />

The HTML comment is replaced with the content of the third instance of the array block's meta variable text.

In order to access a meta variable within an array block that is part of that block, no bracket syntax is necessary. In this case the content is accessed in the same way as if using the variable XX-ARRAY-meta variable name. Example:

<!--ARRAYBLOCK:LENGTH=3-->
    <input name="IMPERIA:text" type="text" size="30" value="" />
    <!--XX-ARRAY-text-->
<!--/ARRAYBLOCK-->

In the example above, the template processor replaces the section between  and  with the contents of the array block's meta variable text.

One-Click-Edit#

One-Click-Edit is a browser extension of imperia. Editors can use it, for example, to import the corresponding document directly from the Archive for editing, while they are viewing the published page on a live system. Details for the usage of One-Click-Edit can be found in chapter One-Click-Edit of the user documentation. For information about the configuration see One-Click-Edit in the administration documentation.

As far as template development is concerned, you may store the relevant for One-Click-Edit information in the following way:

<!--IMPERIA:LIVEEDIT-->
<!--IMPERIA:ONECLICKEDIT-->
<!--IMPERIA:ONECLICKEDIT_FILE-->
<!--IMPERIA:ONECLICKEDIT_DOCUMENT-->

With the comment  you make imperia store the relevant information in a specific namespace. In it you see, for example, the following code in the published documents:

<imp:live-info sysid="12345678-1234-abcd-efgh-1234567890ab" 
node_id="/2/3/13" />

Note

This special namespace is categorized as invalid by most HTML validation tools.

The comment  generates a meta tag with the relevant information in the published document:

<meta name="X-Imperia-Live-Info"
content="12345678-1234-abcd-efgh-1234567890ab/2/3/13" />

Note

This notation complies to the XHTML specifications.

The variant  is used in relation to copy pages. In this case, the meta tag in the finished document additionally contains the path and filename of the corresponding copy:

<meta name="X-Imperia-Live-Info"
content="12345678-1234-abcd-efgh-1234567890ab/2/3/13-/path/to/document/filename.html" />

This makes it possible for functions like Delete to remove only the corresponding copy. The other copies, as well as the master document (if published) remain on the live system. If there is no copy page present, this variant has no particular effects.

The comment  is equivalent to .

Note

The last two variants of the One-Click-Edit comment can also be formed with the standard variant  and the system configuration variable “ONECLICKEDIT” from the file site/config/system.conf.
Set the variable to the value “file” in order to process copy pages individually. Every other value requires processing on document base.
For further information about the configuration variable ONECLICKEDIT enquire System Configuration Variables.

Convert Plug-ins (postconvert)#

imperia provides a number of plug-ins that trigger conversions that are always performed, when a template is parsed. This is the case, for example, when a preview of a document is generated from the Archive or when a document is edited.

In general, a plug-in is called like this:

<!--postconvert:PLUGIN_NAME(ARGUMENTS)-->
<!--postconvert:PLUGIN_NAME-->

The first directive shows an invocation of the plug-in PLUGIN_NAME with arguments, the second one without. Many plug-ins have reasonable defaults, and may be invoked without arguments.

Currently the following convert plug-ins are available:

SafeUnicode for transformation of UTF-8 text in compliance with “us-ascii” or “iso-8859-1”.
Recode for transforming text from one codeset into another.
PHPExec for executing PHP code in a template.
Null as a skeleton for your own plug-ins.
DnDTemplates to enable drag and drop in a template.
View for executing imperia's view language code in a template.

SafeUnicode Convert Plug-in#

The plug-in converts special character in UTF-8 encoded texts into HTML entities. The text remains in the UTF-8 character set, but the use of entities prevents errors when displaying special characters. In this way you can make sure that even software that is not Unicode aware will always correctly process texts in UTF-8. With an optional parameter you can specify whether the result of the conversion should be US-ASCII or ISO-8859 compatible. Apart from that, you can use numerical entities. The settings for the conversion procedure are given in the template invocation of the plug-in:

<!--postconvert:SafeUnicde(Parameter|Parameter=Value|...)-->

The parameters can be set at your choice with or without a boolean value. Currently the plug-in processes two parameters:

numerical

If this parameter is set, the plug-in uses numerical entities for special characters, for example & instead of &. This variant offers a little better performance and compatibility, since some browsers ignore more recent entities as, for example, €.

latin1

When you pass this parameter, the plug-in only converts characters that come after the first 255 characters in the character table. The range for control characters (128-159) is ignored by the plug-in. You should not use the parameter when the edited text must be compatible to the CP-1252 (Windows-1252) or ISO-8859-15 (Latin-9) character sets.

If you use no parameters, the plug-in works with the default settings. That means that it converts characters over position 127 into entities (US-ASCII compatible) and uses, as long as they are present, the named entities.

Example for an invocation with values:

<!--postconvert:SafeUnicde(latin1|numerical=1)-->

Recode Convert Plug-in#

This plug-in converts text from one charset into another.

You can use the plug-in within a template with the following syntax:

<!--postconvert:Recode(source codeset|destination codeset)-->

Example:

<!--postconvert:Recode(ISO-8859-1|UTF-8)-->

This example converts texts from ISO-8859-1 into UTF-8.

PHPExec Convert Plug-in#

This plug-in starts a PHP interpreter and passes to it PHP code from an imperia template.

In order to activate the plug-in, you can use the following syntax:

<!--postconvert:PHPExec(meta variables)-->

When the template processor finds this code in a template, it starts the PHPExec plug-in. With the optional parameter meta variable you can pass a comma separated list of meta variables to the plug-in, which are then passed as normal CGI form variables to the PHP interpreter.

Example:

<!--postconvert:PHPExec(template, directory, filename)-->

The meta variables appear to the PHP interpreter as form variables. If such a meta variable includes multiple values, multiple variable instances are passed to the interpreter. The string [] becomes the variable name, just as the PHP interpreter expects.

The plug-in is a post processor. All replacements in a template are already done, when the code is transferred to the PHP interpreter. This allows you to use imperia variables in PHP code.

Example:

<?php
   $imperia_template = '<--XX-template-->'
?>

In order for you to be able to use the plug-in, you must set the type and path of the PHP interpreter in imperia's system configuration. For that purpose you should use the variables PHP_CLI and PHP_PATH. More information in chapter System Configuration Variables.

Null Convert Plug-in#

This plug-in serves as a skeleton for your own plug-in development. It contains the function convert() that takes your code.

Note

Further descriptions and more details can be found in the perldoc: /site/modules/core/Imperia/Template/Convert.pm /site/modules/core/Dynamic/Convert/PHPExec.pm /site/modules/core/Dynamic/Convert/Recode.pm

Flex Modules#

Flex modules are available in a standard and a minimal version. The standard version includes all functions, while the minimal version only provides the base functions, which leads to usage limitation.

The integration of a flex module in a template is very easy. Use the following code:

<!--INSERT_FLEXMODULE-->

Further information about flex modules can be found in Flex Modules and Slot Modules.

imperia blocks#

With imperia blocks, a user can duplicate some parts of the template between the opening and closing imperiaBLOCK tags any number of times.

The invocation into a template is as follows:

<!--IMPERIABLOCK-->
  template code
<!--/IMPERIABLOCK-->

The template code between these tags can be arbitrary. The only exception are imperia blocks themselves, since they cannot be nested.

Generating image galleries#

You can generate image galleries by simply adding a specified (MAM call) button within the template.

This will generate pre-assigned assets included within flex modules or imperia blocks. (This process replaces the procedure of first creating flex modules or imperia blocks and secondly uploading the images).

How-to implement the button within the template:

Prerequisites

You will need a Drag&Drop-Template in order to create image galleries. Therefore, enter
 into the desired template.
Also, the flex modules or imperia block need to be enabled by the parameter JS_OPERATIONS=1 in order to use the gallery function.

Please consider that you cannot use LOAD: AJAX within flex modules when integrating the image gallery.

1. Insert code into the template

For the flex/slot module (first part is for the template, second (from AUTHOR) is for the flex module):

    <?imperia mam_gallery
    fill_flex: 102:ga
    button_title: Bildergalerie
    window_width: 500
    window_height: 500
    ?>

    <!--INSERT_FLEXMODULE:INDEX=102:JS_OPERATIONS=1-->

    AUTHOR:  
    DESCRIPTION: 
    LOAD: JSON

    <input name="IMPERIA:myicon_url" type="hidden">
    <img SRC="IMPERIA:myimage" width="300">
    <?imperia mam copy PREVFILE:myicon_url?></img>

For the imperia block:

    <?imperia mam_gallery
    fill_block: 101
    button_title: Bildergalerie
    window_width: 500
    window_height: 500
    ?>
    <!--IMPERIABLOCK:INDEX=101:JS_OPERATIONS=1-->
    <input name="IMPERIA:myicon_url" type="hidden">
    <a href="IMPERIA:MAM:mylink">
    <?imperia mam copy PREVFILE:myicon_url?>
    <?imperia mam setsrc PREVSRC:myicon_url:myicon_img?>

    <img name="IMPERIA:myicon_img" SRC="/imperia/md/defaults/icons/
    ico_smiley1.gif" />
    </a>
    <!--/IMPERIABLOCK-->

The link <img name="IMPERIA:myicon_img" SRC="/imperia/md/defaults/icons/ico_smiley1.gif" /> represents the placeholder image of the MAM call.

2. Set the parameters

Please make sure that fill_block-ID or fill_flex-ID match with the INDEX (in the code example 101).
This ensures the insertation of the images in the desired flex module or imperia block.
In case that the gallery link is inside a slot/flex module, and the target imperiablock or flex is also inside the element you need to address it properly:
```
fill_block: __101
```
OR
```
fill_flex: __102:ga
```
If necessary, customize the size of the MAM window by using the parameter window_width and window_height(in pixel).
You are also able to change the button name by entering a name after button-title.

Codeinclude#

If you want to make your template code easier to maintain, you can store code sections in external files, which can be included in a template. Another benefit of the codeincludes is that you can use them in multiple templates.

imperia expects the codeincludes in the directory /site/include. Under this directory you can structure your include files with subdirectories. The syntax for including external files is as follows:

<!--CODEINCLUDE:directory/filename-->

If there are no subdirectories in /site/include, you only need to give the filename.

Please note that imperia's template processor expands codeincludes included with the syntax described above before imperia blocks and flex modules. Therefore, this syntax cannot be used for includes within flex modules and imperia blocks. Instead use:

<!--CINCL:directory/filename-->

Note

The administration of codeincludes can also be done via the user interface. For more information refer to Codeincludes in the administration documentation.

Files to be added can contain HTML or Perl code. Files with HTML code end with the extension .htms, files with Perl code end with the extension .perl, resp. .pl. Added Perl code is executed by the template processor. The following special Perl variables for codeincludes are available for this purpose:

perl variable	description
$mode	Gives the document mode.
metainfo	Returns a Meta::Info object. Further information can be found in the file `/site/modules/core/Meta/Info.pm`.
$userconf	Returns the values of the registered user.
index	Returns the value of the parameter `INDEX`, when set, resp. `undef`, when the parameter is not set (see below).
$suffix	Returns the appendix, supplemented by imperia to a meta variable, for example, with flex modules and imperia blocks. `$suffix` includes an empty string, when no suffix is attached.
$new	Contains the result of the Perl code, for example the resulting HTML code.
@parameters	Contains a list with parameters, which you have passed in a template with the invocation of a code include (see also next section "Codeinclude parameter Parameter").

Within the codeinclude syntax, you can specify parameters in a colon-separated list. The following parameters are available:

Codeinclude parameter `PARAMETERS`#

This parameter contains a slash-separated (/) list of parameters. The parameters from this list can be queried and used in the added file. The passed strings are escaped with a percent sign (see RFC1630).

Example:

With the following line a file is included in a document with two parameters:

<!--CODEINCLUDE:navi/top.htms:PARAMETERS=one/two-->

In the included file, parameters can be referenced as follows:

<!--CI_PARAM1-->
<!--CI_PARAM2-->

Code-include-parameter `INDEX`#

This parameter determines the index of a code include. The function behaves analogous to the indexes of flex modules. This index is automatically appended to the names of all meta variables.

The index can be referenced as follows:

<!--CI_INDEX-->

Displaying the Document Progress#

For a better visualization of the workflow processes the document progress can be included in templates.

The document progress can be included with the instruction

<!--workflowsteps-->

It will then be displayed at the current position. This tag can be used multiple times.

Note

This tag can also be used in upload templates, except for the flash upload.

With the instructions

<!--imperiaheader-->

and

<!--imperiamenu-->

you can add the header line and the menu line in the header area of a template. These instructions can be used only once.

JavaScript in Edit Mode#

Most of the JS scripts in EDIT mode are placed at the end of the head tag. In your templates, you can use the html comment

<!--imperia-js-files-->

that will be replaced with those scripts.

The following JavaScripts are still located before the closing body tag:

<script type="text/javascript">I.jQuery.toggleConflict(true)</script>
<script type="text/javascript" src="/imperia/js/editmode/collapse.js"></script>
<script type="text/javascript" src="/imperia/js/editmode/control-element-utils.js"></script>
<script type="text/javascript" src="/imperia/js/editmode/base-controls.js"></script>
<script type="text/javascript" src="/imperia/js/lib/plugins/jquery.serializehash.js"></script>
<script type="text/javascript" src="/imperia/js/editmode/js-operations.js"></script>
<script type="text/javascript">I.jQuery.toggleConflict(false)</script>

Including JQuery Scripts#

If you want a plug-in that uses the imperia's internal jQuery to be included, you can use the processing instruction include_jquery. Example:

  <?imperia include_jquery
    script: /imperia/js/dist/jquery.plugin1.js
    script: /imperia/js/dist/jquery.plugin2.js
  ?>

The instruction will temporarily restore imperia's jQuery as the main one, insert the necessary plug-ins, and then bring back your current jQuery version.

Use the script parameter to list the desired plug-ins. It can be used multiple times (as in the example above) and it should contain the path to the script that has to be included.

Setting Default Colors for Tracking Changes#

Changing the default colors for the change tracking can be done within a template with the help of a meta variable. The names of the meta variables are based on the names of the CSS formats.

Note

More information about the change tracking can be found in Tracking Changes in the user documentation and in administration documentation.

If a document contains a meta variable with the name imperiaMinusSpan and the value color: #347F33; background: #235453, these values are used for the representation of deleted text. If you haven't modified a CSS class, imperia uses the default value from the stylesheet.

Example:

<input name="IMPERIA:imperiaPlusSpan" type="hidden" value="color:
##DEADDE; background: red" />

Important

The nested CSS formats (for example imperiaPlusSpan td) in the file diff.css cannot be overwritten with meta variables.

Functions and Constants in Templates#

Below you can find some explanations about the control elements and variables available for templates in imperia.

Hiding Elements#

Particular elements of a template and more particularly explanatory hints can be displayed only during the Edit mode of a document. In the preview or in the final version of a document, these elements should not be present. This can be achieved by hiding these elements depending on the document mode.

There are four different document modes that can be modified with an IF condition (see also Querying and Testing a Mode).

Example:

Enter article text:<br />
  <textarea name="IMPERIA:text_field2" rows="15" cols="40">
  </textarea><br />

In this example the line "Enter article text:" is also contained in the final document. Since this is only an instruction for the editor, such behavior is not desired.

You can avoid this, by displaying the explanatory text only in EDIT mode with the help of an #IF condition:

#IF ("<!--XX-editmode-->")
  Enter article text:<br />
#ENDIF
  <textarea name="IMPERIA:text_field2" rows="15" cols="40">
  </textarea><br />

In this way the line is shown only when the document is in EDIT mode. In order to create other conditions, all operators allowed in #IF conditions are available (see IF Conditions).

You can either group all elements in #IF conditions, or use a distinct #IF condition for each element.

Working with Meta Variables#

As we already explained, imperia stores the content of an input field, named with IMPERIA:fieldname, in a meta variable with the same name. If there are multiple fields with identical names within a template, imperia stores the entered values of these fields as elements of an array in a single meta variable with the same name. When this is not the desired behavior, you must guarantee unambiguous form field names.

Referencing Meta Variables#

You can access values, stored in meta variables, in order to display or test them in #IF conditions. For this purpose, you can use the XX variables. These variables are automatically replaced with the content of the referenced meta variables (see also XX variables and XX-OBJ Variables).

If the referenced meta variable is non-existing, the reference is removed from the final document.

The syntax is XX-meta variable. Example:


This reference returns the title of a document.


This reference returns the directory in which the final document will be stored.


This references returns the content of the meta variable text1 and its content will be displayed in place of the reference.

 This reference returns the path of an object from the Media Asset Management, resp. an object, included in a document with the image upload.

A special feature here is referencing files that have been uploaded into the MAM or with the image upload. These objects can be referenced with the specific variable type XXOBJ. This variable type is recognized by imperia as a file reference. The system places the path to this file at the corresponding location (see also Variables).

Besides XX variables, you can also use CC variables. References with CC variables are URL escaped. For example, a space becomes %20 (see Variables).

Additionally, you can deliberately force an escaping mode for referencing a meta variable, even when this differs from the input one. Use the following syntax:

<!--XX-MODE:meta_field_name-->

In order to force, for example, the interpretation of previously entered text as HTML, you should use this instruction:

<!--XX-HTML:myMetafield-->

For information about escaping modes read Escaping Modes.

Testing Meta Variables#

In some cases it is good to test if a meta variable is empty, so that, for example, the system can start particular actions depending on the result. In order to test if a meta variable is filled in, you should use the following syntax:

<!--XX-DEF-<parameter>meta_variable</parameter>-->

If the tested meta variable is not empty, the test returns 1, otherwise 0. Refer also to XX-DEF Variables.

Querying and Testing a Mode#

A document can be in different modes. You can query, resp. test the mode, using variables. This is particularly important when the readout should be done depending on the document mode. For example, when some explanatory help texts must be hidden in the preview.

In order to check a document's mode in a template, the following code is necessary:

<!--XX-mode-->

This variable returns the current document mode. If the document is in EDIT mode, the variable contains the value EDIT. If the document is in preview mode, the variable contains the value PREVIEW.

If a template is in the mode corresponding to the variable, it contains the value 1 (true), otherwise it contains 0 (false).

The only exception is. This variable contains the value 1, when a document is in save, preview or reparse mode.

In order to check the various document modes use the following syntax:

Variable	Document Mode
<!--editmode-->	EDIT
<!--savemode-->	SAVE, REPARSE, PREVIEW
<!--XX-reparsemode-->	REPARSE
<!--XX-previewmode-->	PREVIEW

Verifying Role Membership#

You can verify whether the user, who is currently editing a document, is a member of a particular role. The result of this verification can be used, for example, as a pre-condition for the display of particular parts of a template. In this way you can make sure that only certain roles see certain elements while editing a document. In order to verify the membership of a particular user to a role, you need the following syntax:

<!--MEMBER_OF:[role_ID | role_name]-->

You can use both the name and the ID of the role you need.

Reading User Data#

This function allows you to refer user data from the user management. You can, for example, automatically add the name or e-mail address of the article author to a document.

In order to access user data from a template, use the following syntax:

<!--XX-USERDATA ... -->

In the following example

<!--XX-USERDATA(format="{fname} {name} <{email}>"):__imperia_uid-->

the first and last names and the e-mail address of the last user who edited a document are written in it. The readout is then, for example:

Guido Flohr &<guido@imperia.bg&>

As you can see the readout HTML is escaped. This behavior can be changed with the “raw” parameter.

<!--XX-USERDATA(format="{fname} {name} <{email}>", raw=1):__imperia_uid-->

If the parameter “format” is left empty, the system will use the value of “login”.

The following values are valid:

Fields Of The User Management:

name	content
id	user id
homepage	homepage
country	country
telnumber	phone number
language	language (de, de_DE, ...)
cellular	cellular
name	name
fname	fname
city	city
zip	zip
zip	zip
login	login
email	email
street	street
comment	comment

When the requested value is not available, an empty string is added.

Important

The old syntax with a dash (USER CONF) is no longer supported!

System Configuration Parameters Readout#

This function makes it possible to refer to system configuration data. All parameters, defined in the file /site/config/system.conf, are available.

In order to access a system configuration parameter, use the following syntax:

<!--SYSTEM_CONF:Parameter-->

Instead of the placeholder Parameter, you use the name of the corresponding system.conf variable. In order to get the configured default language, for example, you should enter the following code:

<!--SYSTEM_CONF:LANGUAGE-->

Pay attention to capital and lowercase letters, underscores, hyphens, etc.

A list of all configuration variables can be found in chapter System Configuration Variables.

Document ID Readout#

The document ID is an integral part of the node ID, which makes every document unique. A node ID consists of two parts:

the category ID, for example: /12/24/35/
the document ID, for example: 130336

The full node ID in this example is /12/24/35/130336. Both the document ID and every single section of the category ID are unique, since imperia generates them from a common, automatically incremented counter.

You can use the following syntax in order to read out the document ID of the current document in a template:

<!--DOC_ID:Format-->

Unlike in previous imperia versions, you can now set more complex parameters. The parameters are optional and make a note in the printf format. An empty string is not a valid format.

Note

You may still use 0 as format definition. This returns the document id which is also the last part of the node id. The same is also achieved with %s.

When you need, for example, a directory counter (similar to the  function), you should use the following syntax:

<!--DOC_ID:%05d-->

Numerical document IDs with less than five digits are left-padded with zeros.

Another example:

<!--DOC_ID:The document ID of this document: %d-->

Calculations in a Template#

There are four main computing types, as well as the equity operator, available in a template in order to manipulate two values. The content of the meta variable can be transferred in the following manner into a computing variable:

<!--TCOUNTER:tcountervar={meta_field_name}-->
<!--TCOUNTER:uid={__imperia_uid}-->

The syntax for calculations in a template is as follows:

<!--TCOUNTER:Name=Value-->
<!--TCOUNTER:Name+Value-->
<!--TCOUNTER:Name-Value-->
<!--TCOUNTER:Name/Value-->
<!--TCOUNTER:Name*Value-->

In the first line the assignment operator = is used in order to generate a new calculation variable, which can be used for calculation.

You can enter either a numerical value or the name of another calculation variable instead of the placeholder Value.

Variables, which do not exist, are automatically generated with value 0. In case of a division by 0, the calculations return an empty string.

Example for simple calculations:

<!--TCOUNTER:var1=4-->
<!--TCOUNTER:var2=2-->
Result:<br />
<!--TCOUNTER:var1+var2-->

Calculation using a constant:

<!--TCOUNTER:var1=4-->
<!--TCOUNTER:var1+dirlevel:0-->

The result of a calculation is displayed in the document.

Category Features Readout#

You may also read out a document's category features and enter them in a document.

Category features can be read out with the following syntax:

<!--SECTION:keyword:category level-->

The following keyword are available:

keyword	description
NAME	Returns the name of the document's category.
DESCR	Returns the description of the document's category.
DIRECTORY	Returns the directory entered in the category management.
TEMPLATE	Returns the name of the template, which is used in the document's category.
FILENAME	Returns the filename which is used in the document's category.
META_INFO_`XY`	Returns the value of the requested `XY` meta variable.

We recommend that only the keywords DESCR and NAME are used, since all other possibilities may not contain the expected value. Furthermore, the initial value, taken from the category management, can change in the course of a workflow.

Here is an example: The main category movies contains a subcategory action. This subcategory contains a subcategory martial arts. In order to get the name of the subcategory action, you must enter the following code:

<!--SECTION:NAME:2-->

If you only want to use the current category level, you do not have to enter a category level:

<!--SECTION:NAME-->

Another example for using keywords. Let's say you have created an additional meta variable, that contains the name of the author. You can then retrieve its content with the following expression:

<!--SECTION:META_INFO_author-->

In case the meta variable is empty, this will return an empty string.

The prefix META_INFO_ is optional and serves for the better diversification of other meta fields. However, if you use meta field names in the category settings, which can also be found in the meta information of a document, the prefix is mandatory. Refer also to Access To Categories' Meta Information.

Path Components Readout#

In correspondence with , there are several other features. As mentioned above, this variable contains the directory in which a document is stored.

You may also access particular parts of the path. To do so you can use the  variable, in which xxx is for the position of the directory in the path, starting with the topmost directory (1).

Let's assume that a document is in the directory /sport/june/16. Then the following code

This article was  created <!--dirlevel:2--> <!--dirlevel:3-->.

in the final document would become

This article was created June 16.

Entering Content in Multiple Languages#

When you use the multilanguage feature of imperia, you don't need to use separate templates for each language. All you need to do is mark the input fields, that will be in different languages with the following instructions:

<!--multilang_start-->

[template code for multi-lang content]

<!--multilang_end-->

Once you have defined the content ranges for the multiple language entry, imperia creates links to the available language versions in Edit mode:

Language selection menu

Click on the desired country flag to select the language. Using the “Copy from...” drop down list, you can copy entered content from one language to another.

Important

Make sure to set fixed indexes with the flex modules. Refer also to .

The input fields for multilanguage content must be provided with a corresponding suffix in order to guarantee that they are unique in the template. Attach the suffix _lingua to the variable name:

<input name="IMPERIA:myfield<emphasis>_lingua</emphasis>" type="text" />

With the comment  you can test or print the current language:

#IF ("<!--XX-lingua-->" EQ "EN")

 [do something]

#ENDIF

In both cases the template processor performs a replacement based on the abbreviation for the current language in the corresponding section.

Note

With input fields in flex modules this is not necessary, since they are already unambiguous because of automatically assigned indexes that are appended to the names (see Using Content Outside Flex Modules).

For more information on imperia's multilanguage feature see Managing Multilanguage Documents With imperia

Adding Time and Date#

You may link date and time in different formats in imperia documents. You have the choice between automatically calculated date and time indications or manually entered ones.

Data Entries with the Calender Tool#

With the calendar tool, you can provide date and time input in your documents with several mouse clicks. The integration in a template is done with a processing instruction. Further settings for the calendar tool are specified via processing instruction parameters. The syntax is as follows:

<?imperia calendar
  parameter: value
  parameter: value
?>

Parameters are entered as a colon-separated name-value pair, each on a separate line. For some parameters, several values are possible. The following parameters are available:

Parameter popup

Set this parameter in order to open the calendar in a popup window. When the parameter is missing, the calendar is always visible in the editing step of a document. The syntax is as follows:

popup: ELEMENT EVENT [SKIN]

The following values are available for this parameter:

ELEMENT
This value specifies the element, that a user must click to pop up he calendar tool. The value default automatically adds a little calendar icon in Edit mode. If you want to use a different HTML element to call the calendar you must give this element an id attribute and set this id as the value for ELEMENT. Here is an example:

<img src="/img/icon/my_calendar_icon.png" id="c_Icon" width="64" height="64" />

<?imperia calendar
    popup: c_Icon click
    [more parameters]
?>

In this example a click on the icon my_calendar_icon.png opens the calendar tool. The link between the icon and the processing instruction is realized with the id "c_Icon".

While the template processor automatically adds the standard icon for calling the calendar tool, you must add an individual element, for example an icon, in the template just as in the example above.

EVENT
Specify a JavaScript event that should trigger the opening of the calendar tool, for example click. The corresponding event must be spelled with lowercase letters only.

SKIN
With this optional parameter you can determine the layout of the calendar tool. Either set an absolute path indication starting from the document root of your system or just the name of one of the following standard skins:

aqua, blue, blue2, brown, default, green, system, tas, win2k-1, win2k-2, cwin2k-cold-1, win2k-cold-2. Please pay attention to the capital and small letters.

These calendar skins consist of a collection of image files and a CSS file. They must be placed in a directory under htdocs/imperia/skin/widgets/calendar.

Parameter connectInputId

This parameter defines which template element to be used by the calendar tool to store the date. This element must be an imperia input field. In order for the calendar tool to be able to access this input field, you must provide it with an id attribute.

Syntax:

connectInputId: element ID "Format"

If you want to use the calender tool in an imperia block, array block, slot module or flex module, you must supplement the id of the input field with the indexes and instance ids of the imperia block, array block, slot module or flex module, since the template processor doesn't adjust this attribute automatically. In a flex module this would look, for example, as the following:

...
<?imperia calendar
popup: default click
connectInputId: date_feld_<!--FLEX_INDEX-->_<!--FLEX_ID-->
[other Parameters]
?>

<input name="IMPERIA:mydate" id="datumsfeld_<!--FLEX_INDEX-->_<!--FLEX_ID-->" 
type="hidden">
...

The date format is set within quotation marks. This string consists of one or more format settings and arbitrary text. If no format is set, unix timestamp is assumed. The available date formats are:

Format instruction	Description
%a	abbreviated name of the day of the week
%A	full name of the day of the week
%b	abbreviated name of the month
%B	full name of the month
%C	Number of the century
%d	two digit day of the month ( 00 - 31 )
%e	day of the month ( 0 - 31 )
%H	hour ( 00 - 23 )
%I	hour ( 01 - 12 )
%j	day of the year ( 000 .. 366 )
%k	hour ( 0 - 23 )
%l	hour ( 1 - 12 )
%m	month ( 01 - 12 )
%M	minute ( 00 - 59 )
%n	New row
%p	`PM'' or`AM''
%P	`pm'' or`am''
%S	second ( 00 - 59 )
%s	Unix time stamp
%t	Tabulator sign
%U, %W, %V	Number of the week
%u	Number of the day of the week ( 1 - 7, 1 = MON )
%w	Number of the day of the week ( 0 - 6, 0 = SUN )
%y	Number of the year without century ( 00 - 99 )
%Y	Full number of the year (e.g. 1979 )
%%	Percentage sign ('%')

An example:

... 
connectInputId: date_field "Selected date:%n %A, %Y-%m-%d, %H:%M:%S%n.
At this point in time 1970-01-01 is %s seconds behind."
...

The following appears in the corresponding meta field: “Selected date: Saturday, 20.10.2007, 23:42:05. By this point in time the 01.01.1970 is 1192916525 seconds behind.”

Note

The code above is wrapped because of representation purposes. In the template it must be in one line.

In order to output the formatting instructions in multiple language, you have to embed them into double brackets. The translations in imperia must be provided in the form of .po files.

Parameter showWeekNumbers

This parameter specifies whether the calendar tools displays week numbers.

Syntax:

showWeekNumbers: true | false

Parameter showTime

This parameter is used to hide and dislay the clock in the calendar tool. If you wish to allow users to change the time, the parameter should be true.

Syntax:

showTime: true | false

Parameter setFirstDayOfWeek

This parameter is used to set the first day of the week; default is Monday. The indication is done numerically, in which the first day, Monday, has the value 1.

Syntax:

setFirstDayOfWeek: 4

In the example above, Thursday is set as the beginning of the week.

Parameter showAdjacentMonths

Use this parameter to enable the display of days of the adjacent months in the calendar tool. The default setting is false (no display of days from adjacent months).

Syntax:

showAdjacentMonths: true | false

The calendar tool with and without adjacent months

Parameter startDate

This parameter is used in order to preset the calendar tool with a date entry. The value has to be given as a unix timestamp. An online tool for calculation in unix timestamp format, including time zone transformation, can be found at http://www.theblog.ca/?p=148.

Example:

startDate: 1193175725

The unix timestamp from this example corresponds to the date 23.10.2007, 23:42:05 o'clock MEZ.

Parameter startYear

This parameter indicats the year at which the year scale of the calendar tool should start.

Parameter endtYear

This parameter indicats the year at which the year scale of the calendar tool should end.

Parameter noSync

When a document is reimported, the date in Edit mode is automatically set to the current date. To prevent this form happening and keep the previously entered date, use the noSync parameter.

Syntax:

noSync: true | false

Parameter seqNumber

Define a sequence number for the calender tool. This parameter is used when more than one calender tools are present in a template.

Syntax:

seqNumber: [number]

When using the calender tool within a MAM multiupload template the value of this parameter should be .

Adding a Date#

The current date can be calculated and displayed in different formats. In order to add the date in a template use the following variable:

<!--Xdate:Format-->

The available displayed formats are:

format name	displayed format
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

A date can also be entered as the value of an input:

<input name="IMPERIA:date" type="text" size="8" value="<!--Xdate:default-->" />

Other Date Functions#

To access individual parts of the date as day, month, year; use the following syntax:

<!--DATE:Format-->

The following formats are available:

parameter	description
day	Day (numeric)
month	Month (plain text)
mon	Month (numeric)
year	Year (numeric)

Adding Time#

In order to assign the time, use the following syntax:

<!--Xtime:Format-->

The following time formats are available:

parameter	description
default	22:14
normal	22:14:18
full	22:14:18
compact	22:14
hour	22
minute	14
second	18

Localized Time and Date#

To format the current date and time via the system function strftime use the following syntax:

<!--Xstrftime:Locale:Format-->

The parameter Locale is for the dependent on the operation system LOCALE variable. Refer to the documentation of your operation system.

Example:

<!--Xstrftime:en_EN: Today is  %A, %Y, %B %d.-->

This syntax returns:

Today is Thursday, August 16, 2011.

Note

All possible HTML signs (smaller than, bigger than, ampersand, double and single quotation marks) in the string, delivered by strftime, are escaped correctly.

Localized Date with Offset#

In order to obtain a date in the future or in the past, one can use offsets. The syntax is as follows:

<!--Xstrftimeoff:Offset:Locale:Format-->

The parameter Locale is replaced by the dependent on the system LOCALE variable. The parameter format sets the desired date format.

Offsets contain an arbitrary number of parameters in the form operator-value unit. The operator is optional. If there is no operator given, the value is added to the current date.

The following offset operators are available:

operator	description
+	Adds the next value to the current date, resp. time.
-	Subtracts the following value from the current date, resp. time.

The following values for offset parameters are available:

parameter	description
s	seconds
m	minutes (always 60 seconds)
h	hours (always 3600 seconds)
D	days (always 86400 seconds)
W	weeks (always 604800 seconds, resp. 7 days)
M	months (always 2592000 seconds, for example 30 days)
Y	years (always 378432000 seconds, for example 365 days)

Leap seconds and days are ignored as well as the difference in the number of days in a month.

Examples:

value
`+1W-1D`	Today plus 1 week minus 1 day
`600`	now plus 600 seconds
+1M	Today plus 1 month

The corresponding algorithm is optimized in order to calculate the expected results. When you set an offset of three months on the 13th of a month, the result should be the 13th of the corresponding months. A non existing target date such as for example 31st February would be replaced with the first existing date prior to the desired date.

IF Conditions#

You can use IF conditions to test conditions in a template. According to the result of the test imperia performs the specified instructions. Additionally, it is possibile to test alternative conditions and whether a condition is not applied. Nesting IF conditions is also possible (see also Nested IF Conditions ). The result is either true (also true or 1) or false (also false or 0).

A conditional instruction starts with the keyword IF, followed by the condition, which is set in parentheses and with one or more instructions, which should be performed when the condition is fulfilled. The end of the instruction is marked by the keyword ENDIF.

Optionally, you can add a branch with an alternative instruction block. This can be achieved with the keyword ELSE, resp. ELSIF. Detailed explanations for the different keywords can be found in the following sections.

The syntax for an IF condition is as follows:

#IF (condition)
  code

#ELSIF (condition)
  code

#ELSE
  code

#ENDIF

The keywords for the conditional instruction must be marked with a leading hash sign '#'.
You can also use operators, such as AND, OR and EQ.
A full list of all allowed operators can be found in Operators. Operators can be placed directly after the keyword IF and in parentheses.

The operator AND is assessed with the test of the conditions before the operator OR. If the operator NOT is used, the effect of the operators AND and OR is reversed.

String Comparisons in IF Conditions#

Please note the following when comparing two strings in IF conditions:

Meta variables should be called with TEXT mode. In this mode, HTML code is escaped (see Escaping Modes). It also prevents complications when the content of the meta variable includes an introductory sign.

Keywords in IF Conditions#

The possible keywords in IF conditions are:

IF (`condition`)#

The keyword IF is introductory for the conditional instruction. The condition is placed in parentheses. It is followed by the instructions that imperia must perform in case a condition is fulfilled, resp. in case a test returns a true value.

#IF (condition)

When you want to test that a condition is not met, you should use the following syntax:

#IF NOT (condition)

The result of this test is true, when the condition is not satisfied.

Note

Unlike earlier imperia versions, you must put meta variables within brackets in quotation marks.

THEN#

Use this keyword if an IF query is in a single line. Example:

#IF (condition) #THEN (instructions)

Important

Using the keyword THEN is not recommended as it leads to ambiguity. It is still supported for compatibility reasons.

ELSE#

After the keyword ELSE you should note the instructions, which imperia should perform, when the condition test returns false (see also IF Conditions with ELSE and ELSIF).

ELSIF (`condition`)#

With the keyword ELSIF you should include a branch of the conditional instruction, which imperia performs, when previous conditions return false and when an alternative condition is true (see also IF Conditions with ELSE and ELSIF).

ENDIF#

Closes an IF condition.

Operators#

Both boolean operators and comparing operators are available.

Boolean Operators#

Boolean operators:

Operator	Description
AND	This represents an AND assignment. The AND operator indicates whether both operands are true.
OR	It represents an OR assignment. The OR operator indicates whether either operand is true.
XOR	This represents an either-or-assignemnt. In order for a condition with an either-or conjunction to yield a true value, one operand must be true, the other false.
NOT	This represents negation. The condition is met if the operand after the negation is false.

Comparative Operators#

Comparative operators:

Operator	Description
EQ	This operator test if two values are equal. The code "foo" EQ "foo" is true, "foo" EQ "bar" is false.
NOT EQ (alias NE)	This operator tests if two values are not equal. The code "foo" NOT EQ "bar" is true, "foo" NOT EQ "foo" is false.
CEQ	This operator test if two strings are equal (not case sensitive). The code "foo" CEQ "FoO" is true, but "foo" EQ "FoO" is false.
NOT CEQ (alias NCE)	This operator test if two strings are not equal (not case sensitive). The code "foo" NOT CEQ "bar" is true, but "foo" NOT CEQ "FoO" is false.
REQ	This operator compares a value with a regular expression. You can find more information in Regular Expressions.
LT (or <)	This operator tests if a value is less than a second value. The comparison is performed alphanumerically. That means, when comparing two strings the string whose letters appear later in the alphabet, is defined as greater.
LE (or = <)	The operator test if the value is smaller or equal to a second value.
GT (or >)	The operator test if a value is bigger than a second value.
GE (or >=)	This operator test if a value is bigger or equal to a second value.

Simple IF Condition#

A simple IF statement tests a condition. If the condition is fulfilled, returns true, imperia executes the following instructions. Otherwise, nothing is done. Here is an example:

#IF ("<!--XX-showpic-->" EQ "yes")
  <img src="/images/grafik1.gif" width="40" height="20" border="0" />
#ENDIF

Starts the IF statement. First, the condition to be tested is defined, in this case whether the meta variable showpic contains the string "yes". If this test returns true, imperia performs the following instruction.
At this place you should note one or more instructions that should be performed in case the condition is met. In this example this is the display of an image.
This line ends the IF condition.

IF Conditions with ELSE and ELSIF#

In case of an IF condition with an ELSE branch you can also define instructions for the case, when the requested condition is false. Here is an example:

#IF ("<!--XX-editmode-->")
   <img src="/images/dummies/topnavi_dummy.gif" border="0" />
#ELSE
   <!--CODEINCLUDE:navigation/topnavi.perl-->
#ENDIF

The condition is true, when the document is in Edit mode. In this case an image is displayed. If the document is in another mode, imperia instead adds a codeinclude in the image's place.

If you would like to test more than one case and if you want different instructions to be executed, you can use the definition of the alternative conditions with ELSIF.

#IF ("<!--dirlevel:2-->" EQ "football")
  <img src="/images/icons/football.gif" border="0" />
#ELSIF ("<!--dirlevel:2-->" EQ "hockey")
  <img src="/images/icons/hockey.gif" border="0" />
#ELSIF ("<!--dirlevel:2-->" EQ "basketball")
  <img src="/images/icons/handball.gif" border="0" />
#ELSE
  <img src="/images/icons/sport_default.gif" border="0" />
#ENDIF

In this example multiple tests are done one after another on the second category level of a document. If it is "football", the image football.gif is displayed. If this is not correct, imperia checks the next condition, etc. The ELSE branch represents the (optional) default case of this conditional instruction. If all the other test have returned false, imperia executes the ELSE condition.

AND assignment#

An AND assignment contains at least two conditions and only returns true when all conditions are met. The syntax is as follows:

#IF ((condition1) AND (condition2))
  instruction1
  instruction2
#ENDIF

OR Conjunction#

An OR assignment contains at least two conditions and returns true, if at least one condition is met. The syntax is as follows:

#IF ((condition1) OR (condition2))
  instruction1
  instruction2
#ENDIF

Nested IF Conditions#

Nested IF conditions test conditions depending on other conditions.

You can nest instructions to arbitrary depth. But you should consider that the more nested conditions there are, the slower the processing speed will be. In order to keep a good overview of the deeply nested IF conditions and in order to keep the maintenance easier, you can add HTML comments.

The following example shows the syntax for a nested IF condition:

        #IF ("<!--dirlevel1-->" EQ "sport")
          #IF ("<!--dirlevel:2-->" EQ "football")
            <img src="/images/icons/football.gif" border="0" />
          #ELSIF ("<!--dirlevel:2-->" EQ "hockey")
            <img src="/images/icons/hockey.gif" border="0" />
          #ELSIF ("<!--dirlevel:2-->" EQ "handball")
            <img src="/images/icons/handball.gif" border="0" />
          #ELSE
            <img src="/images/icons/sport_default.gif" border="0" />
          #ENDIF
        #ELSIF ("<!--dirlevel1-->" EQ "culture")
          #IF ("<!--dirlevel:2-->" EQ "theater")
            <img src="/images/icons/theater.gif" border="0" />
          #ELSIF ("<!--dirlevel:2-->" EQ "ausstellung")
            <img src="/images/icons/museum.gif" border="0" />
          #ELSIF ("<!--dirlevel:2-->" EQ "konzert")
            <img src="/images/icons/music.gif" border="0" />
          #ELSE
            <img src="/images/icons/culture_default.gif" border="0" />
          #ENDIF
        #ENDIF

In the example above the system test the top directory level of a document. Depending on the result of this clause, imperia tests a number of other optional conditions for the second directory level. The result of the second test finally triggers the display of a certain image.

The start of the conditional statement. imperia should test the first directory level of a document.
If the test of the first condition returns true, imperia executes the next instruction block. This is a test for several conditions for the second directory level of a document, similar to IF Conditions with ELSE and ELSIF.
End of the instruction block, that imperia executes if the first condition is met.
This line contains the definition of the second condition for the first nesting level of the conditional instruction.
In this line the instruction block for the second condition starts. It again goes about the testing conditions for the second directory level of a document.
In this line the conditional instruction for the second nesting level ends.
This ENDIF marks the end of the entire conditional instruction.

Comments in #IF Conditions#

In order to get a better overview of the deeply nested IF conditions, you may add HTML comments. The syntax is as follows:

<!--This is a comment-->

Regular Expressions#

Regular expressions are a series of symbols and syntax elements, used to find particular patterns within texts. They can be used for all types of text manipulation. In functions such as search, resp. search and replace, they provide, for example, the refinement of the search criteria. When searching a text or a data stream, regular expressions serve for testing particular conditions.

In the following sections you can find a couple of simple examples for the use of regular expressions in the conditional instructions in imperia.

Examples for Regular Expressions#

The following code tests if the meta variable defaultimage ends with the string default.jpg:

#IF ("<!--XX-defaultimage-->" REQ "default\.jpg$")

The following syntax tests if the meta variable textfield contains at least 10 characters:

#IF ("<!--XX-text_field-->" REQ ".{10}")

The following code tests if the meta variable keywords contains the word computer:

Note

You cannot perform such a test with the other operators.

#IF ("<!--XX-keywords-->" REQ "computer")

The following syntax tests if the data readout in a meta variable originates from the month december:

#IF ("<!--XX-date-->" REQ "^12\.\d{1,2}\.\d{2,4}")

Dynamic Modules#

With the dynamic modules you can replace particular parts of a template using HTML code or the content of external files. It is even possible to use only one single template, which is modified accordingly by dynamic replacements.

The replacements, which should be performed with the dynamical modules, can be configured in the site/config/dynamic.conf file. As an introduction, see this little example for entries in this file:

IF [<!--dirlevel:1-->] EQUALS [agenda] OR [news]
OR [politics] OR [tnt]
REPLACE [<!--standard-desc-->] BY[online department - agenda]
REPLACE [<!--standard-key-->] BY [online department, tv, news,
background, reports, football, sports, gossip, weather, real video]
REPLACE [<!--main-navigation-->] BY [FILE:n_ak_ne.txt]
REPLACE [<!--sub-navigation-->] BY [FILE:nsakne.txt.txt]
FI

The following sections explain the syntax of dynamic.conf. Some examples for the functions and the possibilities can be found in Simple Replacements.

Syntax Reference for the `dynamic.conf`#

The used in dynamic.conf syntax is very simple and has minimum keywords. In general a valid instruction is built in the following manner:

IF [value1] EQUALS [value2] OR [value3]
REPLACE [string] BY [string] TIMES [number of replacements]
REPLACE...
REPLACE...
FI

The keywords in details:

IF

The keyword IF introduces a comparison. Values to be compared, should be in square brackets.

EQUALS

The keyword EQUALS is the comparison operator. The value in the first pair of brackets, resp. the contents of the entered meta variable, must match the value of the second pair of brackets, resp. the content of the entered meta variable.

OR

This keyword triggers an OR conjunction. It allows the inclusion of multiple values in a comparison. It testes whether at least one of the entered values meets the condition. An AND conjunction can only be emulated with two subsequent IF conditions.

REPLACE

This keyword introduces replacement. It is followed by the string, which should be replaced, in square brackets. After this string the keyword BY must follow (see below).

BY

This keyword is followed by the character string in square brackets, with which the defined by the REPLACE character string is replaced.

TIMES

This keyword is used in a REPLACE instruction to limit the replacements performed.

FI

Closes an IF condition.

Simple Replacements#

Below is a simple example to make the mechanisms and functions of the dynamic templates understandable.

As a precondition we need:

A template which has the word section at some place. This word should later be dynamically replaced.
Four categories: sport, politics, arts and culture.
A meta file per section. Each meta file must refer to the relevant category-associated directory.

To edit the dynamic.conf, open it in the internal editor or in an arbitrary external editor.

Note

The original dynamic.conf includes example codes. You can comment them with hash signs (#) or you can store the existing dynamic.conf under a different name.

Enter the following code:

IF [<!--dirlevel:1-->] EQUALS [sport]
  REPLACE [section] BY [Category: <b>Sports</b>]
FI
IF [<!--dirlevel:1-->] EQUALS [politics]
  REPLACE [section] BY [Category: <b>Politics</b>]
FI
IF [<!--dirlevel:1-->] EQUALS [culture]
  REPLACE [section] BY [Category: <b>Culture</b>]
FI
IF [<!--dirlevel:1-->] EQUALS [art]
  REPLACE [section] BY [Category: <b>Art</b>]
FI

The first line compares the content of the first meta variable  with the string sport. Remember: this meta variable contains the first part of the path of a file (see also Path Components Readout). If the content of the meta variable is equal to the string, the condition is met and the second line, the REPLACE instruction is processed.

The REPLACE instruction searches the template for the content of the first square bracket pair and replaces it with the content of the second square bracket pair. In our example also the string section is replaced by the string category:Sport . As you can see, you can also use HTML code that is displayed in the template correctly.

The last line contains the keyword FI which terminates the IF construct.

The other three IF conditions of this example work on the same principle: if a particular condition is met, a defined string is replaced by another one.

Replacement by an OR Assignment#

An OR conjunctions tests if at least one the specified conditions is met. If this is the case, the instructions given are executed.

In the following example the background color of the site is replaced depending on the directory:

IF [<!--dirlevel:1-->] EQUALS [sport] OR [politics]
  REPLACE [#ffffff] BY [#009933]
FI
IF [<!--dirlevel:1-->] EQUALS [art] OR [culture]
  REPLACE [#ffffff] BY [#cc3300]
FI

Both OR conditions work in the same way. It is checked wheter the value of the meta variable  corresponds to the string sport or the string politics. If the condition is fulfilled, the replacement is performed.

AND assignment#

In the syntax of dynamic.conf there is no direct AND assignment. An AND assignment can, however, be emulated by two nested IF constructs:

IF [<!--dirlevel:1-->] EQUALS [sport]
  IF [<!--dirlevel:2-->] EQUALS [tennis]
    REPLACE [type] BY [tennis]
  FI
FI

Defining the Number of Replacements#

If the string to be replaced is present multiple times in a template, you can also define, how often the replacement should be done. This is done via the keyword TIMES. The syntax is as follows:

IF [expression] EQUALS [string]
  REPLACE [search string] BY [replacement string] TIMES [number of replacements]
FI

Example:

IF [<!--XX-replace-->] EQUALS [1]
  REPLACE [section] BY [Category: <b>Sport</b>] TIMES [5]
FI

This example tests if the meta variable  has the value 1. If this is the case, the string section is replaced five times by the string category: sport.

Replacement by an External File#

You can also replace an arbitrary string in a template with the content of an external file. This function is of benefit when the replacement contains multiple lines. The external files, are not subject to name conventions, but they must be stored in the /site/dynamic directory in ASCII format.

The syntax is as follows:

IF [expression] EQUALS [string]
  REPLACE [search string] BY [FILE:filename]

Loading Parts of the `dynamic.conf` from External Files#

The dynamic.conf can grow significantly and become hard to maintain. For this reason it is possible to include external files, and thus reduce the size of dynamic.conf.

The loaded files can be attached at the end of dynamic.conf. There are no name conventions for these files, but they must be in the /site/dynamic directory or in a subdirectory.

An invocation of an external file is as follows:

IF [expression] EQUALS [string] INCLUDE [filename]

Example:

IF [<!--XX-template-->] EQUALS [news] INCLUDE [basic.conf]

This example tests if the name of the used template is news. If this is the case, the file /site/dynamic/basic.conf is attached at the end of dynamic.conf.

Loading an External File from a Subdirectory#

If the external file is in a subdirectory of the /site/dynamic directory, the invocation is as follows:

IF [expression] EQUALS [string] INCLUDE [path/filename]

Example:

IF [<!--XX-day_of_week-->] EQUALS [monday] INCLUDE [day_of_week/monday.conf]

The code tests if the meta variable  contains the string monday. If this is the case, the content of the file /site/dynamic/day_of_week/monday.conf is attached at the end of dynamic.conf.

Drag and Drop in Edit Mode#

imperia already contains an implementation for a Drag and Drop mode in templates. The current implementation is based on jQuery, and uses both a different approach and a new design.

If you want to enable Drag and Drop, you should select the standard.html view in the call parameter VIEW. That view allows interaction with the instances by means of dynamic control elements.

The new options and view are valid for all modules that you can include in templates. At the same time the work with flex modules, slot modules and imperia blocks becomes simpler and more dynamic. All of the following options can be activated independently from each other. Several options can be activated at once, using a colon-separated list in the module call.

The parameter CONTROL_WIDTH determines the width of the control element until a module has been inserted. Once an element had been inserted, a frame is displayed around the corresponding module. The parameter INSTANCE_WIDTH controls the width of that frame.

Set the parameter JS_OPERATIONS to 1 in order to enable dynamic loading of flex modules with JSON.

Make sure that your template contains the postconvert directive:

<!--postconvert:DnDTemplates()-->

Collapse instances#

If the parameter COLLAPSE was given, a button is added to all instances of the module that can be used to collapse and expand all instances. This makes it easier for editors to see the structure of a document.

Example call:

            //The following code is wrapped for representation purposes
<!--INSERT_SLOTMODULE:VIEW=standard.html:CONTROL_WIDTH=1000px: 
  INSTANCE_WIDTH=1002px:COLLAPSE=1-->

<!--INSERT_FLEXMODULE:VIEW=standard.html:CONTROL_WIDTH=500px:COLLAPSE=1-->

Drag and Drop for instances#

The parameter DND enables Drag and Drop for instances within a module (now also with nesting of modules).

Example call:

        //The following code is wrapped for representation purposes
<!--INSERT_FLEXMODULE:VIEW=default.html:JS_OPERATIONS=1:CONTROL_WIDTH=500px:
    DND=1-->

and for imperia blocks:

<!--IMPERIABLOCK:INDEX=30:DND=1:JS_OPERATIONS=1:VIEW=standard.html-->
  <input name="IMPERIA:imperiablocktext" type="text"></input>
<!--/IMPERIABLOCK-->

Drag and Drop for MAM#

You can adapt/deactivate the View of the DnD upload.

Therefore, adapt the following sample files to your needs that are to be found under /site/view/imperia/default/controllers/document/media/upload/:
- custom_meta.html.sample
- custom_meta_header.html.sample
Save them without the ending .sample.

Functions via JavaScript#

To run the functions “Delete”, “Clone” and “Paste” via JavaScript you need to enable the option JS_OPERATIONS. To use these functions you need to activate the module LOAD: JSON or LOAD: AJAX in the corresponding template.

Example call:

<!--INSERT_SLOT:CONTROL_WIDTH=850px:VIEW=standard.html:DND=1:JS_OPERATIONS=1-->

The Template Processor#

The template processor is called whenever a document is edited in the Edit step. It evaluates all functions contained in a template. Because of that the template processor tests which of the possible modules are included within a template.

The different modules are processed in a fixed sequence - the template chain. You can influence the sequence via the system configuration variable TEMPLATE_CHAIN in the system.conf file.

Important

If this variable is set, then all documents are processed only with the modules listed there. Changes done this way are globally valid for your system.

When you don't want to change the template chain for your entire system, you can control it with the meta variable __imperia_template_chain for every category, resp. every document.

The default template chain is:

Note

The text is wrapped for representation purposes.

DynamicConf,CleanActive,CodeInclude,Multilang,Slot,Flex,ImperiaBlocks,Array,
CodeInclude:CINCL,Convert,Realobjects,CleanTemplate,Control,Localization,
Expansion,FormFill,AC,LiveEdit,JavaScript,CSS,DynamicConf,Generator,Convert

Deactivating Modules#

If you are sure that you don't use particular modules in your project, you can reconfigure your template processor. This will increase the performance of your system, as only the necessary modules will be executed.

Important

Deactivating necessary modules can have unexpected results when processing templates. Refer to The Template Processor's Modules for information about the various modules. Deactivate only modules you are sure are not necessary.

If you know that you wouldn't need some of the available modules, remove them from the list in TEMPLATE_CHAIN.

Example:

Note

The text is wrapped for representation purposes.

TEMPLATE_CHAIN" = "CleanActive,CodeInclude,Flex,CleanTemplate,Control,Localization,
Expansion,FormFill,AC,LiveEdit,JavaScript,Generator,Convert

Changing the Module Order#

The preset order in which the various modules of the template processor are executed, makes the use of certain constructs impossible.

In such cases you can change the template chain. Here is an example:

You want to use two alternative codeincludes loaded depending on the location of a document: the directories releases/news and releases/archive. The codeinclude are named after the directories:

releases_news.htms and releases_archive.htms

In a template, you specify the filename of the codeinclude with the following construct:

<!--CODEINCLUDE:<!--dirlevel:1-->_<!--dirlevel:2-->.htms-->

With the default template chain this construction wouldn't work. Instead of the contents of the codeinclude, only a comment appears in the document, for example:

<!--CODEINCLUDE:news.htms-->

The reason for this is that the expansion of imperia variables is done after the execution of codeincludes. When the include file is loaded in the file, the content of the variable dirlevel:1 and dirlevel:2 is not known and thus the filename cannot be built.

The default execution order of template processor modules is as follows:

Note

The text is wrapped for representation purposes.

DynamicConf,CleanActive,CodeInclude,Multilang,Slot,Flex,ImperiaBlocks,Array,
CodeInclude:CINCL,Convert,Realobjects,CleanTemplate,Control,Localization,
Expansion,FormFill,AC,LiveEdit,JavaScript,CSS,DynamicConf,Generator,Convert

The module CodeInclude is responsible for the expansion of include files, and the evaluation of imperia variables is done in the module Expansion. The template processor processes the different modules from left to right in the order they are in the template chain.

In order for the above mentioned constructions for the codeinclude filename to be functional, you must also change, resp. supplement, the sequence of modules.

Important

Changes in the execution order of absolutely necessary modules can lead to unexpected results. Refer to The Template Processor's Modules for information about the individual modules.

Besides the codeinclude, all imperia or array blocks, as well as flex modules, have access to imperia variables. When you move the module Expansion before CodeInclude, you will probably get errors in the further processing of templates.

You can instead add an additional invocation of Expansion in the template chain, so it looks as follows:

Note

The text is wrapped for representation purposes.

"TEMPLATE_CHAIN" = "DynamicConf,CleanActive,Expansion,CodeInclude,Multilang,Slot,
Flex,ImperiaBlocks,Array,CleanTemplate,Control,Localization,Expansion,FormFill,
AC,BlackMan,LiveEdit,JavaScript,CSS,DynamicConf,Generator,Convert"

The multiple execution of template processor modules puts more load on the system. This additional load can be avoided if you limit the appropriate changes to the documents, where necessary.

The Template Processor's Modules#

Below is a list with brief explanations of the modules that the template processor uses.

Note

The template processor further expands multilingual content in each of the below mentioned steps.

Array

This module is responsible for the processing of array blocks (refer also to Array Blocks).

CodeInclude

The evaluation of codeincludes, slots and flex modules is done in this module.

Control

This module evaluates the included in a template code control structures such as #IF, #ELSE and #ENDIF (refer also to IF Conditions).

Convert

This module controls the conversion of text data in a template (refer also to Convert Plug-ins ).

Dynamic

This module executes the replacements that have been specified in the dynamic.conf file (refer also to Dynamic Modules).

Expansion

Variables are expanded with this module (see also Functions and Constants in Templates).

Flex

The module processes flex modules in a template (see also Flex Modules and Slot Modules).

Slot

The module processes slot modules in a template (see also Flex Modules and Slot Modules).

Multilang

The module processes multilingual documents.

FormFill

This module serves for processing forms and input fields.

ImperiaBlocks

This module processes imperia blocks in a template.

JavaScript

This module provides a JavaScript library for the edit mode.

Localization

This module controls the localization of meta files and template code.

ClearTemplate

Initialization of the template.

ClearActive

Initialization of the template.

JWord

This module converts the special instructions of the Java wordmodule to object and embed tags.

Onload and Onsubmit Handlers#

If for some reason you need to prevent page loads and form submits in a template, imperia provides a jQuery library that can be used for such cases.

Example JavaScript code, for load events:

/* Listening for the load event */

 I.jQuery(window).on('load', function() {

     // your code

 });

Example JavaScript code, for submit events:

/* Listening for the submit event */

 I.jQuery('#imperia').on('submit', function(event) {

    /* To stop the submit process, simply prevent the default
     * action of the event:

          event.preventDefault();

     */

     // your code

 });

Template Examples#

Copy the files in /site/sample/templates to /site/templates and choose one of the templates as a default for a category.

/site/sample/templates/flashupload.htms - assets upload through a template in imperia 10 with the help of a flash module.
/site/sample/templates/mediaupload.htms - the traditional assets upload through a template in imperia 10.
/site/sample/templates/mediaupload_custom_fields.htms - the traditional assets upload through a template in imperia 10.
/site/sample/templates/catmeta.htms - special template for the management of meta categories in imperia 10.
/site/sample/templates/news.htms - a basic multilanguage template that creates a "News" document with title, teaser and text box.

imperia's Full Text Search Templates#

imperia's full text search uses templates for the input of search queries and the display of search results. You can define templates for a simple and advanced searches and for a results page.

You can find example templates for a simple and an advanced search mask and for a results page in the site/fts/templates directory. These example templates are also the default search masks and results page, which are used when you work with the search without further configuration. Refer also to chapter imperia's Full Text Search of the administration documentation. The full text search uses these templates automatically when you invoke the search script as follows:

http://your_server.net/cgi-bin/fts_search.pl

With these parameters you use the simple search mask without additional options. To call the advanced search mask use the following URL:

http://your_server.net/cgi-bin/fts_search.pl?ADV=1

Enter a search term and send a request. imperia's full text search processes this and delivers the search results as a hit list. The way this hit list looks can be controlled from a template. A sample template for this is automatically selected, when you use the default settings. Information for creating your own result templates can be found in Result Templates.

Search Templates#

The search template contains as a minimum an HTML input field to enter search term as well as a button for sending the request. These control elements can be attached to a document with a form. In the action attribute of the form enter the URL of the search script:

<form action="/cgi-bin/site_search.pl" method="post">

All parameters can be added as a query string to the invocation of a search script. This variant is of benefit when you want to offer an input field for search requests as standard operation element on all pages of your project.

More flexibility, for example, with regard to the selection of alternative layout variants or the refinement of the search requests can be guaranteed, when you specify the search mask as an individual template and do not link directly, but let it parse by the full text search.

Some parameter, for example, the URL of the search script or the layout variant for the result template, can be referenced as variables in the search template. The invocation of a search template is done via the search script in the cgi-bin directory. The script then loads the real search mask and fills the variables in the template with the corresponding values.

An example for such use of template variables is the action attribute of the search form:

<form action="[!--FORM_ACTION--]" method="post">

The search script fills this variable with the corresponding value, which in this case is a reference to itself, so that users receive an HTML site, which source code corresponds to the hardcoded example in the beginning of this section.

An example for a simple search template:

<html>
  <head>
    <title>Imperia - Full Text Search>/title>
  </head>
  <body>
    <form action="/cgi-bin/[!--FORM_ACTION--]" method="post">
      Please enter a search term:<br />
      <input name="SEARCH"><br />
      <input type="submit">
    </form>
  </body>
</html>

Transfer Parameters and Variables in Search Template#

Along with the search term, you can control other parameters via the input fields in the search form. These are sent to the search script when sending the form.

Alternatively, you can also attach this parameter in the references to the search script as query string to the URL. The following template variables and parameters are available:

SEARCH

The name attribute of the search term input.

Example:

<input type="text" name="SEARCH" value="">

GROUP

With this parameter you can transfer groups used to filter the search request. The value must be at least one of the declared group names.

The groups for the filtering can be defined in the index configuration. Refer to chapter Indexing Configuration (index.conf) of the administration documentation.

GROUP filtering can be deactivated either by giving it a value of 0 or omitting it.

You can use selects, checkboxes or radio buttons for groups selection in the search form. Multiple selections are also possible with the multiselect fields.

Example:

<input type="checkbox" name="GROUP" value="DVD">
<input type="checkbox" name="GROUP" value="CD">

If you use select boxes for selecting groups in a search template, you can have them automatically filled with options for existing groups. To do that set double quotation marks in the name attribute of the select field and then define the groups to be automatically entered in the site/config/fts.conf file as templateDynamicGroups. Refer to chapter Search Configuration (fts.conf) of the administration documentation.

You can also write more options in the value when using a simple select field.

Example:

<select name="GROUP">
    <option value="">All</option>
    <option value="apples">apples</option>
    <option value="pears">pears</option>
    <option value="cheese">cheese</option>
    <option value="fruit">fruit</option>
</select>

Please note that in this case the different group names should not be divided by pipe sign ("|"), but with space.

DATE

Restricts the search to the last xx days.

Example:

DATE = 0 : today's documents
DATE = 7 : this week's documents

The selection of different amount of time can be done via checkboxes or select fields.

<select name="DATE">
  <option value="0">today</option>
  <option value="7">last 7 days</option>
</select>

HTML_NR

Use this parameter to determine which template variant to be used. The value is the number, which you have defined in the site/config/fts.conf file with the template control variables. In templates, this parameter has to be set in hidden fields.

Example:

<input type="hidden" name="HTML_NR" value="3">

ADV

If this parameter is set, the FTS uses the advance search template.

Example:

<a href="[!--FORM_ACTION--]?ADV=1">extended search</a>

DATE_START

You can also limit the DATE filter to a range of dates. Use DATE_START to define the start date. The FTS considers the date of the last modification of a document.

Example:

<input type="text" name="START_DATE" value="">

DATE_STOP

With this parameter you set the end date.

Example:

<input type="text" name="DATE_STOP" value="">

WCOUNT_MIN / WCOUNT

If you want only documents with a minimum number of words to be displayed in a hit list use this parameter. The parameter WCOUNT is synonymous with WCOUNT_MIN.

Example:

<input type="text" name="WCOUNT_MIN" value="">
<input type="text" name="WCOUNT" value="">

WCOUNT_MAX

With this parameter you filter out documents that have a greater than the maximum number of words.

Example:

<input type="text" name="WCOUNT_MAX" value="">

LANG

Specify a language variant to enable the evaluation of language-specific substitutions in the search. These language-specific substitutions are defined in the search configuration.

Example:

<input type="hidden" name="LANG" value="DE">

INPUT_LOCALE

Configure a character set to be used in the entries in the search form. This method helps you resolve problems with language-specific special characters.

Example:

<input type="hidden" name="INPUT_LOCALE" value="ISO-8859-1">

OUTPUT_LOCALE

Configure a character set, to be used in the readout of the search results. This method helps you resolve problems with language-specific special characters.

Example:

<input type="hidden" name="OUTPUT_LOCALE" value="ISO-8859-1">

SORT

With this parameter you can determine the sorting sequence of the hit list. The following values or the parameter SORT are possible:

Parameter	Explanation
`arelevance`	Ascending sorting according to relevance.
`drelevance`	Descending sorting according to relevance. (Default)
`amodified`	Ascending sorting according to modification date.
`dmodified`	Descending sorting according to modification date.
`asize`	Ascending sorting according to file size.
`dsize`	Descending sorting according to file size.
`awords`	Ascending sorting according to word count.
`dwords`	Descending sorting according to word count.

Note

In general, the hit list is sorted in a descending order according to relevance. All sorting options defined by a user or the configuration influence this presorted list.

TYPE

Use this parameter in order to limit the search to particular document types. The following table shows the possible values for the parameter. Multiple entries are also possible.

Values for the parameter TYPE:

Parameter	Description
`HTML`	Searching only HTML files.
`TXT`	Searching only text files.
`XPDF`	Searching only PDF files.
`DOC`	Searching only Microsoft Word files.
`XLS`	Searching only Microsoft Excel files.
`PPT`	Searching only Microsoft Powerpoint files.

Result Templates#

Apart from the control elements for further search request, the results template contains the HTML output of a search result. This output can be controlled with a number of special template commands.

The commands are put between HTML comment signs  or square brackets [!-- --]. Both would have the same meaning.

With WYSIWYG editors, it is beneficial to be able to enter visible and hidden commands. When you use square brackets, the template commands remain visible in the preview of the editor, while HTML comments are hidden. In order to achieve this, the WYSIWYG editor does not move the latter, for example, between table rows in HTML code. Which type of brackets is used is of no importance for the search.

Example for a simple results template (for better differentiation the template commands are in square brackets):

<html>
  <head>
    <title>FTS Results</title>
  </head>
  <body>

  <!-- Section for repeated search -->
    <form action="[!--FORM_ACTION--]" method="post">
      Search for :<br />
      <input name="SEARCH" value="[!--SEARCH_REQUESTED--]"><br />
      <input type="submit">
    </form>

  <!-- Result section -->

  [!--SEARCH_WORD_RESULT--]
  "[!--SEARCH_REQUESTED--]" found in [!--RESULT_TOTAL--] documents. <br />
  [!--/SEARCH_WORD_RESULT--]

  [!--SEARCH_WORD_NOTFOUND--]
  The query "[!--SEARCH_REQUESTED--]" did not match any documents. <br />
  [!--/SEARCH_WORD_NOTFOUND--]

  [!--SEARCH_PAGE_RESULT--]
  [!--RESULT_NR--]. <a href="[!--PAGE_URL--]">Filename: [!--PAGE_URL--]</a><br />
  [!--/SEARCH_PAGE_RESULT--]
</body>
</html>

The following section explains the template commands used in the example above.

Search Term Commands#

SEARCH_REQUESTED

This is the field for receiving a search term that a user had entered in the search query. This is beneficial in order to predefine the content of an input field.

Example:

<input type="text" name="SEARCH" value="[!--SEARCH_REQUESTED--]">

SEARCH_WORD_RESULT

Use this command to define a block in which you can write more commands to display search results.

Syntax:

[!--SEARCH_WORD_RESULT--]
  [more template instructions]
[!--/SEARCH_WORD_RESULT--]

The following orders are available:

WORD_SEARCH_REQUEST_FOUND - this instruction generates a reference to a detailed search, with the corresponding search term, for every contained in a results page search term.

Example:

Let's assume that the search term is "imperia full text search". The results page will display the following links:

<a href="fts_search.pl?search=Imperia">Imperia</a><br />
<a href="fts_search.pl?search=fulltextsearch">Fulltextsearch</a>

WORD_FOUND - This command provides the search term.

WORD_COUNT_FOUND - provides the number of documents, in which the search term has been found.

META_KEY - this is the name of the meta field in which the search term has been found.

META_DETAILS....../META_DETAILS - the listed within this block instructions apply only to meta information. The following instructions are at your disposal:

META_WORD_COUNT_FOUND - behaves as WORD_COUNT_FOUND, but applies to meta information.

META_WORD_FOUND - behaves as WORD_FOUND, but applies to meta information.

The results are displayed for each word from the search.

Note

The suffix _FOUND can be omitted. This changes the behavior of the corresponding template commands so that hits, which have been hidden because of different filters, are displayed.

SEARCH_WORD_NOTFOUND

This is a template command to output parts of a keyword or keywords in all failed requests.

Syntax:

[!--SEARCH_WORD_NOTFOUND--]
  [more template instructions]
[!--/SEARCH_WORD_NOTFOUND--]

in this block you can note the following command:

NOTFOUND_WORD = Not found word

Displaying Stop Words#

Requests, which contain only stop words, deliver no hits. If along with the stop words the request contains other search terms, the full text search delivers all documents, which contains these words. That includes documents in which only the other search words appear, but not the stop words. In order to make the search result more transparent in such a case, you can disply stop words in their own area of a results template.

SEARCH_WORD_BLACKLISTED

With this command you include the block of instructions that handle stop words. In the block you can note other template commands and markup.

Syntax:

[!--SEARCH_WORD_BLACKLISTED--]
  [more template instructions]
[!--/SEARCH_WORD_BLACKLISTED--]

BLACKLISTED_WORD

This command is a placeholder. The stop words from the query appear in its place in the search results.

A block for displaying stop words in a results template could look like the example below:

[!--SEARCH_WORD_BLACKLISTED--]
  Stopwords contained in query:<br />
  <b>"[!--BLACKLISTED_WORD--]"</b></br>
[!--/SEARCH_WORD_BLACKLISTED--]

Commands for Error Handling#

You can define a formatted readout of error messages in the results template.

ERROR

In this block you format the output of an error message. The message itself you refer to with the command [!-- ERROR_MESSAGE --].

Example:

[!--ERROR--]
<tr>
  <td colspan="3">
    </br>The following errors occurred:
    <b>[!--ERROR_MESSAGE--]</b>
  </td>
</tr>
[!--/ERROR--]

Importants and non-critical error messages are displayed in this block.

FATAL_ERROR

The content of this block is displayed in case of critical errors which have resulted in aborting a search.

Example:

[!--FATAL_ERROR--]

<tr>
  <td colspan="3">
    </br>FATAL Error occurred. For more information check the error log.
  </td>
</tr>

[!--/FATAL_ERROR--]

QUERY_ERROR

This command allows you to control where and how search term input errors are displayed.

Example:

<tr>
  <td colspan="3">
    </br><!--QUERY_ERROR-->
  </td>
</tr>

Commands for the Found Documents#

Use the following commands to control the output of the information in the found documents.

SEARCH_PAGE_RESULT

All commands for operating the given information via the found documents can be noted within this block.

Syntax:

[!--SEARCH_PAGE_RESULT--]
  [more template instructions]
[!--/SEARCH_PAGE_RESULT--]

The following template commands are available for the output of information about search results:

RESULT_NR = current number of result.

PAGE_RANK = evaluation of a result. This is an abstract value that is calculated based on the frequency of a search term in the corresponding document.

PAGE_PERCENT = evaluation of a result. The value is not a percentage! This instruction was adopted for compatibility reasons with the old full text search. The indicated value is the result you get with the command PAGE_RANK.

PAGE_WORDS = number of words in a document.

PAGE_FOUND_WORDS = a list of terms which are found in the corresponding document.

PAGE_FILE = a document's filename.

PAGE_FILE_URL = document's path, including the filename.

PAGE_TYPE = any text that specifies the type of the found document. This information comes from processing each parser. Example: 'Portable Document Format (PDF) ' or ' HTML'.

PAGE_SIZE = document's size in kilobytes.

PAGE_SIZE_BYTE = document's size in bytes.

PAGE_URL = document's path and file name.

PAGE_DATE = document's modification date.

PAGE_TIME = time of a document's last modification.

PAGE_META:XXX = readout of the text blocks, extracted from a document, during the indexing.

XXX = the name of a text block

Optionally, you can also specify a text block's length and to what length it should be reduced. This can be achieved by setting "=CHAR(MIN=YYY;MAX=YYY;CUT=YYY)" after the text block. Instead of "CHAR" you can also use "WORD".

Another modifier is the FILTER directive. The only filter available at the moment is DateTime:

[!--PAGE_META:file_modified=CHAR(MIN=1,FILTER=DateTime::day) --]

Possible parameters to the DateTime filters are day, month, and year. The effect of the directive is that the contents of the meta field file_modified is “filtered” and replaced by the day of the month, the month (as a number from 1-12) or the year.

In order to make this work, the meta field file_modified must contain a Unix timestamp.

With "CHAR" the indications of MIN, MAX and CUT concern letters, with "WORD" - words. MIN, MAX and CUT can be set arbitrarily. MIN controls the minimum length of a text block; MAX - the maximum length. With CUT the length of a text block can be set to an arbitrary length. The remaining part is not displayed.

You can specify multiple, subsequent text blocks separated by a "||" sign. If the first text block is not displayed because it contains too little words, the next one will be tested, etc.

Example:

If the title is at least one sign, it is displayed, otherwise the text “No title” is displayed.

[!--PAGE_META:TITLE=CHAR(MIN=1) || "No title"--]

The following example is not a fixed text, but depends on the presence of the value “formular_url"”. Either this value or the URL of the document itself is displayed:

[!--PAGE_META:form_url=CHAR(MIN=2) || "<!--PAGE_URL-->"--]

You can also test two or more variables:

[!--PAGE_META:name=CHAR(MIN=2) || title=CHAR(MIN=2) || "- no title -"--]

CURRENT_PAGE = current result page

RESULT_BEGIN = start of the current result number for the current page

RESULT_END = end of the current result number for the current page

RESULT_TOTAL = total number of the found documents

CGIFORM:PARAMNAME = readout of the URL parameter with the name PARAMNAME, which is passed to the script. The value is HTML escaped.

Displaying Multiple Result Pages#

If the search results take up more than one page to display, the full text search provides a way to navigate between those pages. This navigation can be influenced with the following instructions in the template:

SEARCH_NEXT_PAGES ...... /SEARCH_NEXT_PAGES

This allows the display of the next and previous result pages. The following commands are interpreted within this sequence:

PAGE_NR_URL = path and filename to the current printout page

PAGE_NR = number of the printout page

SKIP_CURRENT ...... /SKIP_CURRENT = deletes the included HTML code, when the result page is equal to the current result page.

SKIP_FIRST ...... /SKIP_FIRST = deletes the included HTML code when the result page is equal to the first result page.

SKIP_LAST ...... /SKIP_LAST = deletes the included HTML code, when the result page is equal to the last result page.

SKIP_NOT_CURRENT ...... /SKIP_NOT_CURRENT = deletes the included HTML code, when the result page is not equal to the current result page.

PRINT_CURRENT ...... /PRINT_CURRENT = shows the included HTML code, when the result page is equal to the current result page.

PRINT_FIRST ...... /PRINT_FIRST = shows the included HTML code when the result page is equal to the first result page.

PRINT_LAST ...... /PRINT_LAST = shows the included HTML code, when the page with results is equal to the last result page.

NO_RESULT_DELETE ...... /NO_RESULT_DELETE

The included HTML code is deleted, when there are no results.

NO_RESULT_PRINT ...... /NO_RESULT_PRINT

The included HTML code is deleted, when there are results

NO_NEXTPAGE_PRINT ...... /NO_NEXTPAGE_PRINT

No page number is shown, when there are results.

SINGLE_PAGE_DELETE

The included HTML code is deleted when there is only one result page.

SINGLE_PAGE_PRINT

The included HTML code is shown when there is only one result page.

Example:

[!--NO_RESULT_DELETE--]
    [!--SEARCH_NEXT_PAGES--]
        <!--SINGLE_PAGE_DELETE-->
            More matches:
            [!--SKIP_CURRENT--]
                <a href="[!--PAGE_NR_URL--]">
            [!--/SKIP_CURRENT--]
            &nbsp;[!--PAGE_NR--]&nbsp;
            [!--SKIP_CURRENT--]
                </a>
            [!--/SKIP_CURRENT--]
        <!--/SINGLE_PAGE_DELETE-->

        <!--SINGLE_PAGE_PRINT-->
            No more result pages!
        <!--/SINGLE_PAGE_PRINT-->
    [!--/SEARCH_NEXT_PAGES--]
[!--/NO_RESULT_DELETE--]

Search Indexing Control Tags#

It is possible to influence the indexing of HTML documents with special tags. Using those tags, you can extract parts of documents from the indexing or set additional meta fields for the search.

 ...... 

Normally all texts, which are in the body tag of an HTML document, are captured during the indexing, so that a user can search for them. However, with the tags  and  you can define content that should not be indexed. This is mostly beneficial with navigations, headers, footers, etc.

Example:

<html>
    <head>
        ...
    </head>
    <body>
        <!--IFTS_NO_PARSE-->
        ...
        This part does not get indexed.
        ...
        <!--IFTS_PARSE-->
        ...
        This part gets indexed.
        ...
        <!--IFTS_NO_PARSE-->
        ...
    </body>
</html>

With the tag “IFTS_META” you can extend meta values specifically for the search. Case is ignored when specifying meta variables; they must, however, be defined in the configuration file index.conf.

Example:

<html>
    <head>
        <title>Page Title</title>
    </head>
    <body>
        ...
        <!--IFTS_META_TITLE extended for full text search-->
        ...
    </body>
</html>

The indication of the title in the search result would look like the following in this example: “Page title extended for full text search”.

Extend Templates with Internationalization#

The strings in templates that have to be translated are marked by a translation function. These strings are then written to an external file, displayed as a vocabulary list. Once you enter the translations, imperia will display the strings in the user language.

Multilingual templates can be managed easily with an external gettex file. Gettex provides the opportunity to gradually introduce new languages by expanding the set of strings, which you can easily edit.

Note

To get a better overview of the process and go into more detail read the site/po-templates/00README.txt file.

Prerequisites#

To use gettext, you currently need a standard POSIX shell and several utility programs that are usually installed on every POSIX system. Additionally, you need the GNU gettext tools and GNU make. Both can be installed via the package manager of every major operating system.

Marking Strings#

In all your templates, you can mark strings for translation. When a template gets rendered into HTML, the strings are then translated if a translation is available. Otherwise they will be kept as is.

Strings can be marked in several ways:

Simple Translation

<h1>{% __('Welcome to Our Intranet') %}<h1>

Interpolate variables into the translated string:

{% __x('Last edited by {user}.', user => '<!--XX-USER:name-->') %}

Note

For more options (correct plural handling, context, etc.) see the perldoc for Dynamic::ViewImport::I18N and for its underlying module Locale::TextDomain.

Important

Note that the strings within the functions __() and __x() are escaped. If any of the terms in the string are in HTML tags, for example, they will not be executed.
To avoid this you can use the function raw(): {% raw (__('Please do not do that!')) %}

If possible, it is recommended to not use this function at all!

Triggering Translation#

The translation is triggered by the postconvert plug-in, which can be called anywhere in a template. The plug-in should be called only once:

<!--postconvert:View(textdomain=messages)-->

This instructs imperia to run the final output of the normal template processor through imperia's View processor before rendering the content. That means that you can use all features provided by imperia's View processor.

Note

For further options refer to the perldoc for Dynamic::Convert::View

Updating the File List#

Create a file POTFILES.in in the /site/po-templates directory, which lists all templates, flex modules, slot modules and codeincludes. Then, use the command make potfiles for the initial version of POTFILES.in. You can either maintain the list manually, or run the command make potfiles again, when you have added translatable files.

Configuring the Makefile#

Copy the PACKAGE.sample in the /site/po-templates directory to a file PACKAGE and edit it. Follow the code comments.

The Make Targets#

The Makefile in this directory has several targets. Use the make all command for an overview.

To build individual targets, you can pass them as parameters to make. Alternatively, you can always run make all:

make pot
The target re-generates the message catalog messages.pot. It is located in the /site/po-templates directory.
make update-po
Adds the new strings in to the .po files of the different languages.
make update-mo
Compiles the .po files into binary message catalogs.
make install
Installs the translations in the .mo files into your templates.
make potfiles
Updates the list of templates in POTFILES.in.

Adding a Language#

Before you can add a language, you must first create the POTFILES.in file and create the message catalog messages.pot with the command make all. See also The Make Targets.

If you want to add, for example, French as a language, you add “fr” to the variable LINGUAS in the /site/po-templates/PACKAGE file. Then you copy the message catalog messages.pot to fr.po.

You have to edit the header of the file. Two values are mandatory. The first one is the Content-Type. Change CHARSET to the character set of your message catalog which should be UTF-8.

Next, you need to change the Plural-Forms line. To find out which settings you need for your language refer to the gettext documentation at `http://www.gnu.org/s/hello/manual/gettext/Plural-forms.html.

Note

Most PO file editors fill these fields automatically.

Translation#

Important

Before you start translating, make sure that your PO files are up-to-date by running the command make update-po.

To translate, you edit the PO files for the respective language in /site/po-templates manually. The files are human-readable, but it is strongly recommended to use a special editor. For more information, click the following editors to get to their websites:

Better PO Editor
POEdit
GNU Emacs with PO extension
GTranslator
Lokalize
Pootle

Note
Pootle is not a local editor, but a translation server. If you are interested in a web-based solution Pootle could be suitable for you. Nevertheless, it requires substantial administration.

By default, the current language of the user is used for the language of the translation template.

In order to change this (e.g. to have the English Version for the English page in the Edit Mode, and German language for the German page, and so on) it is necessary to add after

<!--multilang_start-->
      [...]
#IF (<!--XX-editmode-->)

the following code

{% old_locale = set_locale('<!--XX-lingua-->') %}

Installing a Translation#

Once the translation in the PO files is done, you must convert them with the command make update-mo in binary files and then use the command make install to install the modification in your template. Finally, you have to re-generate the content with imperia's template reparser to make the translations visible.

Possible Problems and Pitfalls#

The functions __() etc. serve a double purpose. They mark the strings as translatable so that they can be extracted into the message catalog, and when the templates are rendered they lookup the translation.

The original string is the key that is used for the lookup in the translation catalog and it must therefore be constant. It is an error to use variable strings, for example:

{% __("Document created by <!--USER_CONF:name-->.") %}

This is syntactically correct but does not work. The string "" is expanded before the function __() is called. The function is therefore called with something like "Documented created by superuser." or whatever the name of the user is.

The solution is to mark the variable parts as placeholders, and use the function x() instead of ():

{% __("Document created by {name}.", name => "<!--USER_CONF:name-->") %}

The lookup key is now constant and expanded after the translation has been retrieved.

Multiple Sites#

If you run multiple site and want to reduce the size of your translation catalogs, you can split everything up into different text domains. In brief, this is done as follows:

For each text domain you use, you need a copy of the /site/po-templates directory. Edit the PACKAGE file in each directory, and you must maintain the POTFILES file manually in each directory.

In your templates, you must pass the textdomain parameter to the “View” postconvert:

<!--postconvert:View(textdomain=zweitauftritt)-->

You must still maintain "POTFILES" manually for each text domain!
The rest of the process goes just like for the default text domain.

Reparse Documents#

When you have made changes to your templates, documents that have already been published or are in a workflow still use the previously defined template.

To apply such template changes, you need to reparse the documents that use the modified template. imperia provides a reparse tool, that can be found in Menu -> Structure -> Template Reparser. For more information on the Reparser enquire the section Template Reparser in the administration documentation.

Templates

Conventions for Filenames and Keywords#

Template Fundamentals#

Allowed Characters in Variable Names#

Scripts, Forms, Frames and Layer/ILayer in Templates#

Favico.ico#

Syntax Reference#

Template's Body#

HTML Escaping Modes#

Input Field#

Textarea#

Hyperlinks#

Combo Box#

MultiSelect Elements#

Checkbox#

Radio Buttons#

File Upload (Media Asset Management)#

Flash Multiupload (Media Asset Management)#

Images' Aspect Ratio#

Array Blocks#

Access to Array Instances#

One-Click-Edit#

Convert Plug-ins (postconvert)#

SafeUnicode Convert Plug-in#

Recode Convert Plug-in#

PHPExec Convert Plug-in#

Null Convert Plug-in#

Flex Modules#

imperia blocks#

Generating image galleries#

Codeinclude#

Codeinclude parameter PARAMETERS#

Code-include-parameter INDEX#

Displaying the Document Progress#

JavaScript in Edit Mode#

Including JQuery Scripts#

Setting Default Colors for Tracking Changes#

Functions and Constants in Templates#

Hiding Elements#

Working with Meta Variables#

Referencing Meta Variables#

Testing Meta Variables#

Querying and Testing a Mode#

Verifying Role Membership#

Reading User Data#

System Configuration Parameters Readout#

Document ID Readout#

Calculations in a Template#

Category Features Readout#

Path Components Readout#

Entering Content in Multiple Languages#

Adding Time and Date#

Data Entries with the Calender Tool#

Adding a Date#

Other Date Functions#

Adding Time#

Localized Time and Date#

Localized Date with Offset#

IF Conditions#

String Comparisons in IF Conditions#

Keywords in IF Conditions#

IF (condition)#

THEN#

ELSE#

ELSIF (condition)#

ENDIF#

Operators#

Boolean Operators#

Comparative Operators#

Simple IF Condition#

IF Conditions with ELSE and ELSIF#

AND assignment#

OR Conjunction#

Nested IF Conditions#

Comments in #IF Conditions#

Regular Expressions#

Examples for Regular Expressions#

Dynamic Modules#

Syntax Reference for the dynamic.conf#

Simple Replacements#

Codeinclude parameter `PARAMETERS`#

Code-include-parameter `INDEX`#

IF (`condition`)#

ELSIF (`condition`)#

Syntax Reference for the `dynamic.conf`#

Loading Parts of the `dynamic.conf` from External Files#