Flex and Slot modules

For information on slot modules read from section Slot Modules in this chapter.

Flex modules#

Flex modules are HTML blocks that a user can insert when creating an article. The user can combine them as often as desired in arbitrary order.

The flex modules must be stored in the /site/flex directory of your develop system. The availablity to a template modules can be restricted, using VALIDCODES and INVALIDCODES directives.

When a user creates a document with a template that includes a flex module, he or she will see a designated area where a flex module can be inserted. Depending on the view selected by the template developer, this area might look like the following:

Flex Module

Any number of flex modules (instances) can be inserted in a template.

This documentation describes the default flex module view - base.html.

You can define a system-wide default view for control elements, using the system configuration variable EDITMODE_DEFAULT_CONTROL_VIEW. Also, you can use the meta variable __imperia_editmode_default_control_view to overwrite the system-wide settings for a given document or category.

Structure of a Flex Module#

Flex modules can contain HTML or Perl code. You can store HTML flex modules with the extension .htms and Perl ones with the extension .perl, resp. .pl. Each flex module consists of a header and a body. In the header you can define the following properties:

DESCRIPTION of the flex module (optional)
VALIDCODES and INVALIDCODES (optional)
AUTHOR of the flex module (optional)

The header contains information that is displayed in the flex module list and administration. This includes a description (DESCRIPTION), information about the author of the flex module and the VALIDCODES, resp. INVALIDCODES. You also have to specify the way in which a module should be loaded (LOAD). It is mandatory to separate the header with at least one empty line.

Flex module header example:

Important

VALIDCODES, resp. INVALIDCODES, must be entered in the header of a flex module before the empty line.

DESCRIPTION: Textarea
AUTHOR: Imperia Sample
VALIDCODES: culture, sports, events
LOAD: AJAX

[... flex module code ...]

The body contains the actual code that is added by the template processor to a template, when a user selects the desired flex module. It can contain arbitrary HTML or Perl code.

Example:

[Header]
<textarea name="IMPERIA:textOne" rows="7" cols="40" wrap="soft">Text 1</textarea>
<textarea name="IMPERIA:textTwo" rows="7" cols="40" wrap="soft">Text 2</textarea>

imperia supplements the name of every field with an underscore followed by the index id of the flex module and then followed by another underscore and the serial number of the flex module instance (see <--FLEX\_INDEX--> and <--FLEX\_ID-->).

Important

The allowed charecters for the IMPERIA:name attribute are A-Z a-z 0-9 _. Using any other character will result in the system automatically changing the name to imperiaflex, which could cause problems if you are trying to access a certain flex module.

When using conditional statements in flex modules (#ENDIF/#ELSE/#IF), make sure to leave a blank line before the statements.

In case you are using AJAX as a loading method, you can create your custom loading templates. This also works with slot modules and imperia blocks. Example:

{%= #assign(my_slot_loader) =%}
    <h1 data-imperia-ajax="true"> Loading the flex module ... </h1>
{%= #end =%}
{%= js_tmpl(my_slot_loader, 'slot-ajax-loader') =%}

Important

The data-imperia-ajax="true" attribute is mandatory and it should be present only once within a loading template.

Input in a Template#

The behavior of flex modules is controlled by these parameters:

<!--INSERT_FLEXMODULE-->
<!--INSERT_FLEXMODULE:VALIDCODE=xxx-->

The available functions pop up on mouse-over. On the lower left corner of the pop up frame there is a drop down menu that contains the permited flex modules (refer to chapter Flex Modules in the user documentation).

Parameters#

Below is a list of all parameters that can be used in a flex module invocation. The syntax is as follows:

<!--INSERT_FLEXMODULE:Parameter1=value:Parameter2=value:ParameterN=value-->

VIEW#

You can use this parameter, in order to control the appearance of a flex module and the control elements of a flex call. The syntax is as follows:

<!--INSERT_FLEXMODULE:VIEW=name-->

The following is a list of all available values for the VIEW parameter:

base.html - this is the default value.
minimal.html - essentially the same as the default one, but it does not have the drop down menu.
standard.html - available options pop up on mouseover.
default.html - deprecated; only supported for compatibility resons.
compact.html - deprecated; only supported for compatibility resons.

Note

If you are using compact.html, you need to add COLLAPSE=1 to the flex call in order to display the minimize buttons. This parameter has to be added also to the slot module call, in case a flex is inside one.

Of course, you can create your own skins.

VALIDCODE=`value`#

This parameter starts the validation of flex modules. All flex modules,

which VALIDCODES contain the value of the parameter,
which INVALIDCODES do not contain the value of the parameter,
which contain neither VALIDCODES nor INVALIDCODES,

are displayed in the selection list in the flex command module.

VALIDEXP=`value`, INVALIDEXP=`value`#

This is an expanded syntax for the flex modules validation. It allows the use of regular expression for testing if a flex module should be displayed or not.

Regular expressions are testing every flex module in the form ^EXP$/, in which EXP corresponds to the text, which is indicated as a parameter.

Flex modules with INVALIDEXP are tested first and then the ones with VALIDEXP. The first hit is decisive.

INVALIDCODES are ignored. If a flex module has no VALIDCODES, the regular expression tests for an empty string. If there is no concordance, a flex module is shown only when there are no VALIDEXP.

Examples:

expression	explanation
VALIDEXP=imperia.*	corresponds to all VALIDCODES which start with “imperia”.
VALIDEXP=imperia.:INVALIDEXP=.not	finds all flex modules, which VALIDCODES don't end with “not”, but start with “imperia”.
INVALIDEXP=.*	shows an empty selection list in the flex command module and turns off the adding of new instances.
VALIDEXP=	finds all flex modules, which have no VALIDCODES.
VALIDEXP=abc.:INVALIDEXP=abc.	shows an empty selection list in the flex operation, since all flex modules have been turned off with the INVALIDCODE.

INDEX=`xxx`#

This parameter is used to manually set the flex module index. It can be used in order to change the sequence of the flex module list within a template, without changing the index. It is also very practical with copy pages, when using a different template, in which some flex elements are not used.

Note

The behavior is undefined if this parameter is omitted.

ML_INDEX=xxx#

In multilingual documents you must provide a fixed index, using the ML_INDEX parameter. In this way, the template processor automatically supplements the indexes of the flex module copies for the different language versions in increments of one thousand. The interval of this automatic supplement can be set to an arbitrary value in the system configuration variable ML_INDEX[number].

Note

The behavior is undefined if this parameter is omitted.

imperia blocks must be indexed with this parameter as well.

`ALLOW`=`xxx`, `yyy`#

This parameter is used to exclude particular features. By default, all actions are allowed. Multiple actions can be separated by commas. Possible actions include:

action	description
insert	adding new instances
delete	deleting present instances
move	changing the sequence of the present instances
all	all actions are allowed
none	no actions are allowed

Note

This feature does not prevent a user from changing the Flex History, but only hides the corresponding controls.

LABEL#

This parameter provides the option to change the default label of a flex module with standard.html view (“Insert flex modules here!”).

<!--INSERT_FLEXMODULE:other parameters:LABEL=text:other parameters-->

AUTOINSERT#

If this parameter is set, there is no need to use the insert button when adding new flex module instances. Once a flex is selected from the drop down list, it is automatically added below the current module.

Note

AUTOINSERT can also be used with slots and imperia blocks.
Also, it only works with base.html, standard.html and minimal.html views.

<!--INSERT_FLEXMODULE:other parameters:AUTOINSERT=1:other parameters-->

STATIC_MAIN_CONTROLS#

If this parameter is set, the main controls will always stay on top. Example:

<!--INSERT_FLEXMODULE:INDEX=10:VIEW=base.html:DND=1:STATIC_MAIN_CONTROLS=1-->

Result:

Important

This parameter works only with the base.html and minimal.html views.

AUTOSHOW_MAIN_CONTROLS#

If this parameter is set, the main controls are displayed on load. This parameter cannot be used together with STATIC_MAIN_CONTROLS. Example:

<!--INSERT_FLEXMODULE:INDEX=10:VIEW=base.html:DND=1:AUTOSHOW_MAIN_CONTROLS=1-->

Important

This parameter works only with the base.html view.

Flex Modules with Perl Code#

Flex modules can also contain Perl code. If such a flex module is called, imperia executes the included code and outputs the result into the template. Flex modules which contain Perl code, must have the extension .perl, resp. .pl.

Note

By default, Perl flex modules are disabled.

Please follow the instructions, which are described in section Security of the installation documentation.

The configuration variable ALLOW_PERL_UPLOAD controls wheather Perl flex modules can be uploaded and edited.

Example for a flex module with Perl code:

##DESCRIPTION: Perl Example
##AUTHOR: Imperia Sample

$new = "This is a simple example that shows";
$new .= "how to sum two values.";
$new .= ($param1 + $param2);

Unlike in HTML flex modules, you must put a hash sign (' #') in front of all header lines. Only then can imperia execute the Perl code from a flex module.

The flex module from the example above obtains as parameter the values of the drop down lists in the section parameter of the flex module list. The HTML code for the edition stores the module in the $new variables.

With a Perl flex module you can access all data known to imperia:

Element	description
%SYSTEM_CONF	The system configuration data
$local_metainfo	All meta information of a flex module instance.
$metainfo	All meta information in a document.
$mode	The current mode of a document ( EDIT , PREVIEW etc.).
$userconf	Access to the user information. %USER_CONF
@parameters	List of the transfered parameters
$params	Reference to a hash with a flex variable (see Flex Modules Variables). Access is done, for example, via $params->{'flex_id'} for the ID of a flex instance.
$param1	First transferred parameter. Alias for $parameters[0].
$param2	Second transferred parameter. Alias for $parameters[1].

You can allow the execution of an arbitrary Perl code in a flex module. Another example is a table with a variable number of columns and rows. A user specifies the number of rows and columns, using the drop down lists for parameters in the flex module bar. The code is as follows:

##DESCRIPTION: Perl table
##AUTHOR: Imperia Sample

$new = "<TABLE>\n";
for ($i = 0; $i < $param1; $i++) {
  if ($i < 1) { $bgm = "bgcolor=\#aaaaaa";} else { $bgm = "";}
  $new .= "<TR $bgm>\n";

  for ($j = 0; $j < $param2; $j++) {
    if ($j < 1) { $bgm = "bgcolor=\#aaaaaa";} else { $bgm = "";}
    $new .= "<TD $bgm>\n";
    $new .= '<INPUT NAME="IMPERIA:text" SIZE="15" TYPE="text" VALUE="" />';
    $new .= "</TD>\n";
    }
  $new .= "</TR>\n";
}
$new .= "</TABLE>\n";

Flex Modules Variables#

You can access the different variables within an HTML flex module. To do so, use HTML comments. Example:

<!--FLEX_ID-->

List of Variables#

``#

This variable contains a numeric index, which starts with 0 and is incremented by 1 with every new flex module in a template.

`<--FLEX\_ID-->`#

This variable contains a numerical id of the instance of a flex module, which starts with 0 and is incremented by 1 for every flex module of the flex module list.

`<--FLEX\_NAME-->`#

This variable contains the name of the flex module which is identical to the file name of the flex module without the extension ( .htms or .perl / .pl ).

`<--XX-FLEX-`Meta variable`-->`#

This variable contains the value of a named flex module meta variable. imperia expands this variable first for the preview, resp. when storing a document. Moreover, you can modify other values for variables from imperia blocks or array blocks, escaping modes and indexes for access to elements from arrays in the meta field. Here are some examples:

 // Example for an imperia block in a flex module
<!--XX-FLEX-IBLOCK-mytext-->

 // Example for accessing the first element of an array in a flex module
<!--XX-FLEX-mytext[0]-->

 // Example for access with escaping mode
<!--XX-FLEX-HTMLBR:mytext-->

`<--XX-OBJ-`FLEX meta variable`-->`#

If the content of the meta field is a reference to a MAM object or a file uploaded with the image upload, you must use XX-OBJ for the meta field. Only in this way the template processor can correctly resolve the reference to the file. It is also possible to use additional modifiers and indexes (see the previous section).

`<--XX-FLEX-`meta value`-->`#

This variable is used within only one instance of a flex module. It includes a unique numerical value that the system assigns to every unnamed meta variable within this instance. That allows to unambiguously refer to unamed meta variables, too.

`<--FLEX\_POSITION-->`#

This variable describes the position of the current flex module instance within the flex module list. The first instance has position 0. It is counted in descending order contrary to FLEX_ID the FLEX_POSITION of an instance changes, when instances above are removed or added.

`<--FLEX\_COUNTER-->`#

This variable contains the value of FLEX_POSITION increased by one.

`<--FLEX\_TOTAL-->`#

Total number of instances within the flex element.

`<--FLEX\_NEXT\_ID-->`#

The id which imperia assigns to the next instance in a flex element when adding.

Using Content Outside Flex Modules#

You can only reference content from a named meta field outside of a flex module. Via the name of the field as well as the FLEX_INDEX and the FLEX_ID the reference of every field can be established unambiguously. The invocation is done as follows:

<!--XX-meta field name_flex_index_flex_ID-->

This variable has access the content of the meta variable in a particular instance in a particular flex module list. The sorting is done via FLEX_INDEX and FLEX_ID.

An example:

Let's assume that a tempalte contains three flex module selection lists. They have two instances each. Every instance includes an input field with the name street and a further one with the name city .

The FLEX_INDEX for the first flex module list is 0, for the second it is 1 and for the third it is 2. imperia numbers every flex module instance analogous: the first instance of every flex module selection list has 0 as FLEX_ID, the second 1, etc.

On each of these flex module instances you can reference content outside the particular flex module. In order to call, for example, the content of a field city in the second instance from the first flex module selection list, you must contact the following meta variable:

<!--XX-city_0_1-->

The numbering of the flex module selection lists and the instances is also saved when a user additionally changes their sequence in the document.

Accessing the meta fields within flex modules also has a short notation with which imperia automatically supplements the FLEX_INDEX the FLEX_ID of the corresponding module:

<!--XX-FLEX-meta_field_name-->

Inserting Fixed Flex Instances#

You can bind flex module instances in a template, so that a user cannot replace them by other modules or change their place. In general, such flex modules function similarly to the code include. The syntax is as follows:

<!--INSERT_FLEXINSTANCE:ID=5:NAME=D_Text{color:#14892c}:INDEX=0{color}-->

Note

Make sure that inserted Flex must have a numeric INDEX.

This adds an instance of a flex module with the name myFlex. The FLEX_ID is obtained from the value of the ID parameter.

Note

Anonymouse meta field names are deprecated

You should not change the FLEX_ID's after you have attached this template to the first document.

Limiting the Access to Slots and Flex Modules#

In general, all slot or flex modules are included in the selection list and are available to users. This list may be limited and only contain allowed slot and flex modules.

imperia uses the VALIDCODE directive for this purpose. When invoking flex modules in a template, you can pass the corresponding code as a parameter and specify which flex modules are selectable. You can use both numbers and letters. imperia compares this code with all VALIDCODES and INVALIDCODES from the headers of the different flex modules and loads only the matching ones. This serves to both permit and exclude different flex modules.

VALIDCODES and INVALIDCODES could be found in the header of a flex module:

VALIDCODES:[code1],[code2],[...]
INVALIDCODES:[code1],[code2],[...]

VALIDCODES specify when the corresponding module should be displayed in the selection list; INVALIDCODES exclude a module from the list. Multiple values can be given as a comma-separated list without spaces.

Example:

VALIDCODES:1,news,5,7
INVALIDCODES:2,archive,6,8

Note

The values must be unambiguous. You cannot set the same value for both the VALIDCODES and INVALIDCODES at the same time.

By default, flex modules without specified VALIDCODES or INVALIDCODES appear in the selection list, even if there is a VALIDCODE parameter in a template.

In a template, you can include flex modules in the selection list, using the desired value. The syntax is as follows:

<!--INSERT_FLEXMODULE:VALIDCODE=[value]-->

Examples:

<!--INSERT_FLEXMODULE:VALIDCODE=5-->

The selection list from this example contains all flex modules, which have VALIDCODES “5” and all flex modules that have no VALIDCODES or INVALIDCODES. Only flex modules with INVALIDCODES 5 are excluded.

Slot Modules#

Slots are another possibility to group recurring template blocks. The usage of slots in a template resembles the usage of flex modules. You can also include flex modules within a slot which makes the nesting of flex modules possible. However, slots cannot be nested.

Structure of a Slot Module#

Slot modules can contain HTML or Perl code. You have to store the files in the directory site/slot of your development system. In syntax and structure slot modules resemble flex modules. An example for a simple HTML slot modules:

AUTHOR: superuser superuser
DESCRIPTION: 50-50
VALIDCODES: news,termine

<div style="float:left; width:49%">
 <!--INSERT_FLEXMODULE:INDEX=100-->
</div>
<div style="float:left; width:49%">
 <!--INSERT_FLEXMODULE:INDEX=200-->
</div>
<div style="clear:both">
<br /> <hr />
</div>

The same indications as in the header of flex modules are also possible here. Refer also to Structure of a Flex Module.
An empty line divides the header of the module from the body with the actual code.
Including a flex module in a slot. Indicating a fixed index is mandatory, in order for the template processor to be able to align the entered contents even after shifting a slot module.
An empty line ends the module.

Invoking Slots from a Template#

The invocation of a slot in a template is the same as the one for a flex module.

<!--INSERT_SLOTMODULE-->
<!--INSERT_SLOTMODULE:VALIDCODE=xxx-->

Also with slots you have the possibility to limit the selection of the available modules by the use of VALIDCODES (compare sections 'VALIDCODE='' and 'VALIDEXP=, INVALIDEXP='). The use of VALIDCODES and VALIDEXP is analogous to the flex modules.

Limitations of the Usage of Slots#

Currently not all flex module features are implemented for slots. The following limitations exist for the usage of slots:

Slots can be added only at the last place. However, additional prepositioning is possible.

Important

In order to relocate slots with flex modules, you must add an index in the flex module invocation.
The use of anonymous variables is not possible in slots.

Slot Variables#

Slots use the same variables as flex modules. When referencing these variables you should replace the keyword FLEX with SLOT . Here are some examples:

Variable	Meaning
`<!--SLOT_INDEX-->`	Numerical and starting with 0 index of a slot bar. It is increased by one for every slot bar in a template.
`<!--SLOT_ID-->`	Numerical and starting with 0 id of the instance of a slot module within a slot bar. It is increased by one for every slot module of a slot bar.
`<!--SLOT_NAME-->`	The name of a slot module. Corresponding to the file name without the extension.

A full listing of the available variables can be found in List of Variables.

Important

There, change 'SLOT' for 'FLEX'.

Since it is not possible to pass parameters to slots, there is no variable  .

Referencing Slot Content#

In order to guarantee the unambiguousness and referencability of the meta fields in slots, the system attaches an index and an id to every meta field name in a slot. You must supplement them when referencing to the meta field contents in a slot with the meta field name (compare Using Content Outside Flex Modules).

If the access is done within the slot module itself, you can use the modifier SLOT in order to perform an automatic expansion of the index and the id. More information on modifiers and their use can be found in Modifiers for XX variables. Access to array blocks and imperia blocks require additionally the corresponding modifier. An exception are flex modules in slots. They can be directly referenced with the modifier FLEX.

Inserting Fixed Slot Instances#

You can bind slot module instances in a template, so that a user cannot replace them by other modules or change their place. In general, such slot modules function similarly to the codeinclude. The syntax is as follows:

<!--INSERT_SLOTINSTANCE:ID=id:NAME=mySlot-->

This adds an instance of a slot module with the name mySlot. The SLOT_ID is obtained from the value of the ID parameter.

Hierarchy in Template Usage#

When using reccuring structural elements in templates they have the following hierarchy:

Element	may contain
SLOT	FLEXMODUL , IMPERIABLOCK , ARRAYBLOCK
FLEXMODUL	IMPERIABLOCK , ARRAYBLOCK
IMPERIABLOCK	ARRAYBLOCK
ARRAYBLOCK	*

Drag and Drop#

Along with the Drag and Drop settings on the flex and slot modules you must also take into consideration the settings on the template. Refer to Drag and Drop in Edit Mode.

Adjustment to the Modules#

Slot or flex modules which should be used with Drag and Drop, must contain information how these modules should be loaded.

This is the header parameter: LOAD:

Possible values for this parameter are:

RELOAD: the module is added to the page after reload. RELOAD is the default value, in case ...
... JSON is not used. When using JSON, the HTML resulting from the module is stored and can be used multiple times in the page, without the need of a request.
Complex modules for example in Perl often cannot be loaded in this way. To be on the safe side, modules in Perl should be inserted with RELOAD or AJAX.
AJAX: If AJAX is used for a module, this module is loaded via a request. This is also possible for complex Perl modules, as long as this does not change the data in the data storage. Read the next section 'Limitations'

Limitations#

Modules which change the data in the data storage can be loaded only with RELOAD, since otherwise there may be inconsistencies.
If the template processor detects the above limitation with nested JSON modules, it automatically changes to RELOAD.

Flex and Slot modules

Flex modules#

Structure of a Flex Module#

Input in a Template#

Parameters#

VIEW#

VALIDCODE=value#

VALIDEXP=value, INVALIDEXP=value#

INDEX=xxx#

ML_INDEX=xxx#

ALLOW=xxx, yyy#

LABEL#

AUTOINSERT#

STATIC_MAIN_CONTROLS#

AUTOSHOW_MAIN_CONTROLS#

Flex Modules with Perl Code#

Flex Modules Variables#

List of Variables#

#

<--FLEX\_ID-->#

<--FLEX\_NAME-->#

<--XX-FLEX-Meta variable-->#

<--XX-OBJ-FLEX meta variable-->#

<--XX-FLEX-meta value-->#

<--FLEX\_POSITION-->#

<--FLEX\_COUNTER-->#

<--FLEX\_TOTAL-->#

<--FLEX\_NEXT\_ID-->#

Using Content Outside Flex Modules#

Inserting Fixed Flex Instances#

Limiting the Access to Slots and Flex Modules#

Slot Modules#

Structure of a Slot Module#

Invoking Slots from a Template#

Limitations of the Usage of Slots#

Slot Variables#

Referencing Slot Content#

Inserting Fixed Slot Instances#

Hierarchy in Template Usage#

Drag and Drop#

Adjustment to the Modules#

Limitations#

VALIDCODE=`value`#

VALIDEXP=`value`, INVALIDEXP=`value`#

INDEX=`xxx`#

`ALLOW`=`xxx`, `yyy`#

``#

`<--FLEX\_ID-->`#

`<--FLEX\_NAME-->`#

`<--XX-FLEX-`Meta variable`-->`#

`<--XX-OBJ-`FLEX meta variable`-->`#

`<--XX-FLEX-`meta value`-->`#

`<--FLEX\_POSITION-->`#

`<--FLEX\_COUNTER-->`#

`<--FLEX\_TOTAL-->`#

`<--FLEX\_NEXT\_ID-->`#