Appendix

In this chapter you can find additional information about different functions and modules as well as descriptions of topics, which are not necessary connected to imperia, but are useful for understanding imperia or working with it.

imperia Plug-ins for the Daemon Hermes#

By the term Hermes plug-in we understand a module, which contains one or more functionalities, executed by the background daemon according to predefined rules. An important advantage of the plug-ins is their easy integration and removal. They can be integrated or removed while the daemon is running.

By default, imperia is provided with numerous plug-ins which, among other, have the following functions:

automatic publishing
automatic deletion
generating overview pages
importing documents

Thanks to the modularity you can easily enhance the functions of the daemon by adding further plug-ins. The daemon should not be modified. This is particularly true for any type of automatic content import.

Apart from the pure functionality, a plug-in must include an interface with which it can communicate with the daemon. On one hand, a plug-in has to identify itself and perform a compatibility test, on the other hand, it has to communicate, under what conditions the daemon should perform specific functions.

The latter information is stored by the daemon as default values in the execution table. Furthermore, the daemon allows plug-ins to write information into the log file or pass data to other plug-ins.

Plug-ins are implemented as Perl packages. The functionality of a plug-in is provided by its methods.

Plug-in Skeleton Code#

The minimum requirement for a plug-in is to implement the interface to the daemon. This interface must consist of a constructor and an init method.

The constructor receives all necessary information from the daemon and executes the compatibility check. The init method returns the default configuration of the daemon.

Constructor#

The typical constructor of a plug-in looks like the following:

sub new {
    my ($class, %params) = @_;
    my $self = {};
    while (my ($key, $value) = each %params) {
            $self->{'__' . $key} = $value;
    }
    # The named arguments also fit for a Hermes::Logger.
    $self->{__logger} = Hermes::Logger->new(%params, prefix  =>
    'myHermesPlugin');
    # Plug-in is not yet operational. This will be reset to 1
    # by reinit().
    $self->{__bad} = 0;
    bless ($self, $class);
}

`Init` Method#

The init method returns the default values for the execution of individual plug-in methods. An init method with two default inputs looks like the following:

sub init {
   [    { 'FUNCTION' =>'method_one',
          'MAX_RUNTIME' => 10,
          'EXEC_TIME' => 0,
          'PRIORITY' => 10
        },
        { 'FUNCTION' =>'method_two',
          'MAX_RUNTIME' => 3600,
          'EXEC_TIME' => 'no',
          'PRIORITY' => 90
        },
   ]
}

For more information on the exact meaning of the fields, please see section Plug-in Table of the administration documentation.

Methods#

When called, the daemon assigns different parameters to methods. A typical method definition looks like the following:

sub method_one {
  my ($self, $container) = @_;
  my $logger = $self->{__logger};
  $logger->fatal ("plug-in is in bad state") if
          $self->{__bad};
  return 1;
}

The $container variable contains a reference to a hash that is used to exchange information between plug-ins. Every plug-in can read out the hash or add information. New information will only be passed to subsequent plug-ins. At the beginning of each run, the hash table is deleted.

The $logger variable contains a reference to the log function of the daemon. Each plug-in is thus able to write information to the log file.

Error Handling#

If errors occure in a plug-in, they are passed to the daemon and are logged in the log file. Then the daemon stops the execution of the plug-ins and starts the next call in the execution table. If an error occurs in a plug-in, execution still takes place in the next run of the execution table.

The daemon also logs runtime error.

imperia Variables#

In this section you can find a list of the most important meta fields of a document in imperia.

__imperia_node_id

This variable contains the node id of a document. The node id consists of a numeric id of the category and a numeric id of the document. These IDs are used, among other things, to build the directory tree of data storage in the file system.

__imperia_modified

This imperia variable contains the date of a document's last modification.

Note

Consider that when reimporting to the workflow the time stamp in __imperia_modified will be updated.

__imperia_category_template

This variable stores the template used to process the meta information of a category. If this variable is not set, a fallback template is used.

__imperia_created

This variable stores the creation date of a document.

__imperia_mime_content_type

This variable contains the MIME-TYPE of the binary content, which is included in the __imperia_mime_content variable.

__imperia_mime_content

This variable contains a binary object.

__imperia_mime_original

This variable contains the filename of the uploaded file.

__imperia_children

In these variables, the node IDs of cloned from this document documents are stored. This is the counterpart to __imperia_parent.

__imperia_uid

This variable contains the user id of the document creator.

__imperia_last_uid

This variable contains the user id of the user that last edited a document.

__imperia_template_chain

With this variable you can specify an alternative template chain for the category, resp. document level.

__imperia_is_copy

Copy pages are indicated by this variable.

__imperia_meta_expand

This variable contains a flag if a document is still in meta mode.

__imperia_imported

This variable contains the UNIX timestamp of the time at which a document was imported by the Hermes.

__imperia_category

In this variable one must define the import category of a document.

__imperia_parent

This variable contains the node id of the original document of a cloned document (see also __imperia_children).

__imperia_parent_filename

Contains the filename of the master page.

__imperia__parent_directory

This variable contains the directory of the main page.

__imperia_ready_handlers

This variable contains a list of actions that execute as soon as the document is ready.

__imperia_version

This variable contains the imperia version that created a given meta information object.

directory

This variable holds the directory part of a document path.

filename

This variable holds the filename part of a document path.

linguas (optional, inherited by the category information)

This variable is set in the meta information of categories; it defines the available document languages. Languages are listed with their respective ISO 639 language code (de, en, fr, etc.).

template

This variable stores the document template.

imperiablock_count_<ID>

This variable stores the number of the existing block instances in an imperia block element. The ID indicates the corresponding imperia block.

FLEXHISTORY_<ID>

This variable stores the number of the existing flex instances in a flex module element. The ID indicates the corresponding flex.

Managing Multilanguage Documents with imperia#

With the multilanguage concept of imperia the various language versions of a document are integrated in a particular copy page (see also Copy Pages Multiple Language Documents Examples in this chapter).

The different copies are differentiated by an ISO 639 language code attached to the file extension (index.html.de, index.html.en, etc.). The new multilanguage features simplify the generation and editing of these copy pages. Which languages should be supported by a document can be set in the category settings, in a meta file or in a template. The languages are recognized in the following order:

Data in the meta file
Indications in the template.
The entries of the category meta variables, in case that the entries are not available in the template or the meta file.

The following sections describe how to use imperia's multilanguage feature.

Workflow#

The workflow for multilanguage documents must include the “Multilang” plug-in. Usually, the place of the plug-in is before the first Edit step, but in some cases it can and should be placed both before and after the Edit plug-in. For information on the configuration of this plug-in see Multilanguage in the administration documentation.

/<!--XX-lingua-->/<!--XX-directory-->/<!--XX-filename-->

To create directories with different names for each language, use the following:

 <!--SECTION:directory_<!--XX-lingua-->-->/<!--XX-filename-->

In this example, the category meta variable “directory_en” (or “directory_en”, etc.) is used as base for the generated path. Bare in mind, that this meta variable should be existing.

You may also use escaping modes within the path (code is wrapped for representation purposes):

 <!--XX-directory-->/<!--XX_NORMALIZE(lingua=<!--XX-lingua-->):
 title_<!--XX-lingua-->-->.html.<!--XX-lingua-->

In this example, the filename of each document is generated from the language specific document's title (i.e. the variable “title_en” for “English”). Then, the value of this variable is run through the “NORMALIZE” escaper plug-in so that the language specific title is turned into a file-system safe path.

Note

In this case, the “Multilang” plug-in has to be placed both before and after the Edit plug-in.

Category Settings#

To create multilanguage documents, you also need the meta variable linguas set in the category meta information. This variable is an array of ISO 639 language codes and define which languages are available to the corresponding category. The first language from this list is referred to as “primary language”. imperia creates the language selection in the MetaEdit step based on this array. Please note that all documents should also include a “linguas” variable which is a subset of the array in the category settings. The content of the variable in the master document results from the choice taken by an author in the MetaEdit step. Only the value of the respective language version is saved in each copy page.

Meta File#

The language selection is activated in a meta file with the instruction MULTILANG_SELECTION. This instruction specifies the languages available to a document. The actual language selection is done during the MetaEdit step. This behavior can be suppressed with the __ip_no_multilang variable.

Template#

The available languages can also be defined in the meta file using . To mark which template elements you wish to generate in all language versions, use the the  and  comments. A template can include several such comments, but they cannot be nested. For every language version imperia automatically generates a duplicate of this area, which is contained in a div tag in the final document. Selecting with language version to edit is done through a language selection at the top of the page.

The template processor performs the following replacements in a /  area:

The _lingua and  strings are replaced by the current country code of the corresponding section. The XX replacement (only for lingua and without any escaping modes) is done at this time, since the information is often necessary.
The character strings ML_INDEX=25 get replaced. The replacement happens as follows: if you have three languages the index of the first one remains unchanged (INDEX=25), for the next language the system adds 1000, for the third 2000, etc. If the value 1000 is not appropriate, you can configure another arbitrary value with the configuration variable ML_INDEX[number]. Use the syntax . The template processor converts that into the values 25, 1025, 2025, etc.

All meta variables within a multilang area should be suffixed with _lingua or _<--XX-lingua-->. In this way after the automatic replacement, they are unique for each language version. For example, the variable foobar_lingua is displayed as foobar_de, foobar_en, foobar_bg, etc. in the Edit mode of a template.

Flex modules must have explicit indexes which, in the case of multilanguage documents, have to be defined with ML_INDEX= instead of INDEX=. imperia blocks within flex modules can be used ordinarily. However, if imperia blocks are independent of a flex module, they must have a fixed index, defined with ML_INDEX=.

You don't need to use the _lingua suffix for meta variables within flex and slot modules, as their uniqueness is guaranteed by the automatically assigned index. And, anyway, the use of this suffix at this point is too late, since, due to the order of modules in the template chain, the replacement has already taken place. All document modes operate in the same manner, except that the duplication of the long multilanguage areas occurs only in Edit mode.

Copy Pages, Multiple Language Documents - Examples#

Copy pages are automatically generated by imperia from the original, the so called master page. The copies have access to the defined in the master document variables. The content of the copy page, as well as its presentation can be different than the master page.

Copy pages need specially created templates which are then filled with the relevant meta information of the master document and automatically saved as additional HTML files. imperia generates the corresponding files when the document exits the workflow. The author sees and edits the master page and its meta information in the workflow. There is also an option to define an additional hidden selection field that controls the selection of copies for a preview.

There are a lot of ways to use copy pages. For example, you can generate different language versions in other subdirectories or generate versions of a document which are optimized for printing. The following example illustrates the procedure for using three language versions of a document.

The copy function of imperia can be activated by setting a meta variable with a name starting with copy (i.e. “copy_print”, “copypage”, etc.). The only requirement is that its value matches the expected syntax:

path:TEMPLATE=yourTemplate:variable1:variable2:...

Important

Since the real classification of the information and the generating of files is done at the end of the workflow, it is not mandatory to set the copy meta field in the MetaEdit step. Other workflow steps for example a meta setter or an editing step can also be used.

A metafile for three language copies can look as follows:

Note

The code is wrapped for representation purposes.

    TITLE "Multilanguage Example"
    AUTHOR "IMPERIA_RELEASE_VERSION_10"

   #IF ("<!--XX-METAMODE-->")
     HIDDEN "directory:<!--XX-directory-->/<!--count-->"

PRINT "English:<!--XX-directory-->/<!--copycount-->/index.html.en"
        PRINT "Deutsch:<!--XX-directory-->/<!--copycount-->/index.html.de"
        PRINT "Français:<!--XX-directory-->/<!--copycount-->/index.html.fr"

        // Initialize copies.

        HIDDEN "copy:<!--XX-directory-->/<!--copycount-->/ \\
index.html.en:TEMPLATE=i18n_en"
        HIDDEN "copy:<!--XX-directory-->/<!--copycount-->/ \\
index.html.de:TEMPLATE=i18n_de"
        HIDDEN "copy:<!--XX-directory-->/<!--copycount-->/ \\
index.html.fr:TEMPLATE=i18n_fr"

    #ELSE
        HIDDEN "directory:<!--XX-directory-->

        PRINT "English:<!--XX-directory-->/index.html.en"
        PRINT "Deutsch:<!--XX-directory-->/index.html.de"
        PRINT "Français:<!--XX-directory-->/index.html.fr"

    #ENDIF

    SELECTION "no_publish:Publish source document"
        OPTION "1:Nein"
        OPTION "0:Ja"
    ENDSEL

The IF condition shown here is described in greater detail in Counter in the Directory Name.
This code section determines the directory, in which the master document and the ready copies are stored.
This code section represents the paths and the filenames of the various copy documents in the input mask of the MetaEdit step.
The three HIDDEN instructions fill the special meta field copy with the necessary information for the copy pages. Only the most important information is specified, namely the path, the filename and the applicable template for the corresponding copy. Further information on setting up copy pages see in copy.
With the no_publish function you specify whether to publish the master document along with the different language versions. Instead of a HIDDEN field the example uses a selection list. Via this selection list the variable receives a value 1 or 0 (refer also to no_publish).

In order for imperia to be able to associate the specific content to the corresponding copies, the input elements for the various language versions must be marked in the master document template, using _lingua or _. Bare in mind, that _lingua is context dependant and works only with input fields and textareas.

Example:

Important

The code is wrapped for representation purposes.

[...]
<h1>        
    <input name="IMPERIA:title_lingua" id="title_lingua" style="width: 100%;" 
                 value="<!--XX-title-->" />
</h1>
[...]

The examples in this section are one of the simplest ways to generate multilanguage content. For example, it is not necessary to divide the input and output template. Instead, you can handle all this in a single template. However, in this case you need to distribute the content elsewhere, e.g. by changes in the workflow.

Appendix

imperia Plug-ins for the Daemon Hermes#

Plug-in Skeleton Code#

Constructor#

Init Method#

Methods#

Error Handling#

imperia Variables#

Managing Multilanguage Documents with imperia#

Workflow#

Category Settings#

Meta File#

Template#

Copy Pages, Multiple Language Documents - Examples#

`Init` Method#