Siteactive

The automatic page generation in imperia is done in a module called SiteActive. With the help of this module you can automatically generate complex pages with just a few instructions. These instructions can be executed in a particular time interval or when there are changes in an “alarm directory”, i.e. on creation, re-publishing or deleting documents.

The corresponding instructions can be noted in the “SiteActive template”. You can either use imperia's SiteActive syntax or Perl. Along with the SiteActive code, a SiteActive template contains the layout of the overview page.

The content of this page is extracted from documents found by SiteActive in accordance to the defined criteria. This is achieved with the help of YY variables (see YY variables ) that allow access to all meta variables of each document found.

If the SiteActive code is executed in regular intervals on a target system, one obtains continuously updated overview pages as a result. A prerequisite for this is that the background daemon Hermes is running on the target system.

Note

Keep in mind that every SiteActive run generates a corresponding burden on the server.

The automatic execution of a SiteActive is controlled by a system service. This can be done in two different ways:

Via a time interval
Via an alarm directory

Time interval

In order to perform a time-controlled SiteActive, set the appropriate interval in a system service. On the target system, on which the SiteActive code is normally executed, the background daemon monitors the system services and starts SiteActive in the configured interval.

Important

New system services and changes in an existing system services are active only after synchronizing system files to a target system.

Alarm directory

Event driven system services are of benefit when, for example, an overview page of latest news has to be created. In such case, every new piece of news should be a new document.

Overview page

An overview page is created by publishing in a particular directory on a target system. At the same time imperia transfers a notification file from a develop to a target system, stored in the /site/incoming directory. This file contains, among other information, the path of a just published documents.

Hit list

The site_active.pl script reads the parameters and processes the SiteActive code in the imperia blocks of the defined by the TEMPLATE parameter SiteActive template. The result of this is a list of documents - the so-called hit list. This list is maintained for the entire SiteActive process. If multiple blocks with SiteActive instructions, targeting different documents or having different settings, are present in a template, the hit list of a previous block has to be deleted before running a new block of instructions. Refer also to Functions for an Internal Hit List. Moreover, imperia creates separate hit lists for Perl and HTML SiteActives.

The site_active.pl script extracts data, referenced by YY variable, from the content of documents in a hit list and uses it in place of the YY variables (refer to YY variables for information on YY variables). All LIMIT instructions restrict the hit list. Then, the script generates the HTML code for the page.

Further parameters can be given via the configuration of a system service, resp. with manual invocation in the query string. They can be referenced in SiteActive as FF variables. More about the FF variables can be found in FF variables.

imperia blocks

Multiple imperia blocks can be used in one SiteActive. All imperia blocks are processed one after another. Take into consideration that internal hit lists and possible limitations (LIMIT HITS, LIMIT BY METAFIELD, etc.) cannot be deleted automatically after processing an imperia block. This has to be done explicitly in the following imperia block (refer to Example 2: Restricted Link List).

SiteActives can be used both on a develop system and on a live system. The invocation can be done automatically via a system service or manually via a special link (see Calling SiteActives Manually).

Procedure and Components of the SiteActive#

In a simple case imperia executes the following processing steps:

Use of a particular file as a template for the generated HTML page.
Opening one or more directories where the source data is.
Search recursively in this directory for files whose names correspond to a particular template.
Preparing a hit list. It sorts the found hits so that, for example, the newest (resp. the oldest) files should be in the beginning of the hit list. The hit list can be sorted in many ways. Refer to SORT: Sorting a Hit List.
Storing the result in a result page with a specific name in a specific directory.
The content for a SiteActive page consists of documents, that meet the defined criteria. SiteActives can be used both on a develop and on a live systems. The invocation is triggered either automatically via a system service or manually via a special link (see Calling SiteActives Manually).

Prerequisites#

The prerequisites for the SiteActive are:

There must be a SiteActive template. Refer to SiteActives - Examples.
If the SiteActive must run automatically, the background daemon Hermes must be started on the corresponding server. Refer to chapter The Daemon Hermes of the administration documentation.
For the automatic start of the SiteActive there must be a system service for every SiteActive page. Refer to chapter System Services of the administration documentation.
You will also need an additional target system with the target format notification for each target system on which you want to use SiteActives. For the standard target system, imperia automatically creates an additional notification target system and with additional target systems this should be done by you. The basis for all SiteAcitves are the target systems. The notifications start the SiteActives and also transfers a document's content to the target systems.

System Service#

The automatic execution of a SiteActive can be controlled via a system service. imperia distinguishes between time controlled and event triggered system services.

Important

Bear in mind that every SiteActive execution puts load on the server. Avoid unnecessary executions by choosing reasonable time intervals, or rather use event triggered SiteActives.

Along with the execution time, the system service configuration also specifies which template should be used for the SiteActive to be executed, and where and under which name the generated file should be stored. Further parameters are referenceable in SiteActive templates as FF variables. For more information about FF variables refer to FF variables .

The configuration of the system service is described in System Services in the administration documentation.

Notification#

Along with a document, imperia transfers a notification file from a develop to a target system on publish.

This file is stored in the /site/incoming directory.

It contains the target path of the corresponding document as well as the complete meta information.

The background daemon checks the /site/incoming directory continuously for new notification files.

If the target path of a document or a directory corresponds to the alarm directory of a system service, the background daemon starts the corresponding system service.

For this purpose it invokes the cgi-bin/site_active.pl script, in which the configuration of a system service determines the CGI parameters to be passed. After that the actual SiteActive process starts.

SiteActive Templates#

Unlike a common imperia document, the content for a SiteActive document does not result from user input, but from the meta information of other already existing imperia documents.

Along with the markup for the layout, a SiteActive template includes instructions that determine, which documents can serve as a basis and what information should be extracted from them. SiteActive templates can contain imperia specific instructions and Perl code. Unlike regular imperia templates, SiteActive templates are located in the document root of the web server.

SiteActive templates can be maintained with or without imperia. Deciding which option to use, depends on the frequency of changes to the layout or the static contents of a document, generated with SiteActive, and the access permissions to a system.

Maintaining SiteActive Templates with imperia#

You can manage a SiteActive template as normal documents in a category in imperia. This procedure is beneficial under the following circumstances:

The layout of the document is subject to many changes.
Along with the automatically generated contents, documents contain editable components.

Administrative functions, such as the Archive, workflows and Desktop are available in order to regulate the maintenance of the SiteActive template. Via the template functions for suppressing certain template code sections in different modes (e.g. Edit/Preview), the SiteActive code can be hidden.

In principle every imperia document can serve as a SiteActive template. It must only include SiteActive code and be published at a location that is referenced by a system service.

Managing SiteActive Templates without imperia#

It is not absolutely necessary to maintain a SiteActive template with imperia. You can also transfer your template directly on a target system. The following conditions have to be met:

Layout changes are very seldom or not present.
The automatically generated document contains no editable contents.

In this case, you need only one HTML file with the layout of the SiteActive-generated preview page and the SiteActive code for extraction of the content from other documents. This file can be stored on a target system under the path, referenced by the corresponding system service under the parameter TEMPLATE.

Changes in the SiteActive template are only possible through access on the file system level.

Syntax Reference#

imperia provides a number of proprietary template commands for automated page generation with SiteActive. Along with the here described commands, you can also use the described in IF Conditions.

Note

Keywords for conditional instructions in SiteActive blocks can also be noted preceded by $. So both syntaxes #IF, #ELSE, #ELSIF, #ENDIF and $IF, $ELSE, $ELSIF, $ENDIF are valid.

Besides imperia syntax, you can also use Perl for creating SiteActives.

IMPERIA: Including SiteActive Instructions#

SiteActive code is introduced in a SiteActive template with the tag <IMPERIA> and it is closed with the tag </IMPERIA>. imperia's SiteActive syntax is used between those tags. They are to be noted in capital letters. Syntax:

<IMPERIA>

[SiteActive INSTRUCTIONS]

</IMPERIA>

SiteActive instructions with Perl code can be included as follows:

<IMPERIA lang=perl>

[PERL SiteActive instructions]

</IMPERIA>

Multiple blocks with SiteActive code can occur within a template. The system subsequently executes all blocks.

IMPORTANT
imperia does not automatically delete the hit list of documents, which is generated based on the SiteActive instructions in the beginning of an imperia code block, after processing all instructions in this block.

The hit list and all related with this limitations ( LIMIT HITS, LIMIT BY METAFIELD, etc.) remain valid even after a SiteActive run. The following SiteActive block generates a new hit list, but it doesn't overwrite already the existing one and it attaches the new hits to the existing list.

This is also valid for SiteActives from different templates, which run independently at different points in time and have completely different selection criteria. If you want to prevent a SiteActive block to execute instructions on a hit list that originates, even partly, from a previous execution, you have to delete the hit list from the previous run at the beginning of a block. To do so use the instruction CLEARLIST (refer also to Functions for an Internal Hit List) or the Perl equivalent clearlist().

READDIR: Defining a Source Directory#

The directory, in which SiteActive searches for hits, can be determined with READDIR:

READDIR = "/directory1"

or

READDIR = "directory1/directory2"

This function determines the directory to be searched, starting from the document root. This includes possibly available subdirectories. An example:

READDIR = "sports/sailing"

In this example, the SiteActive searches the sport/sailing directory, including all its subdirectories.

In addition, you can determine whether and at what depth subdirectories should be included in a search, using the following parameters:

READDIR = "directory[levels][start_depth]"

The default subdirectory depth is 99 levels.

Important

If the directory names contain minus sign (e.g. /movies-2-99), there is a risk that the here described functionality is triggered. This leads to undesired results. Therefore, it is recommended to use a different character, such as the underscore, instead of the minus sign in directory names.

Examples:

READDIR = "/movies-0"

In this case searches are performed only in the /movies directory, but not in its subdirectories.

READDIR = "/movies-1"

In this case searches are performed in the /movies directory and in all subdirectories from the first level, for example /movies/comedy and /movies/action.

READDIR = "/movies-1-2"

In this case searches are not performed in the /movies directory, but in the /movies/comedy and /movies/comedy/00267 directories and the system doesn't search in lower level directories.

SETDIR: Defining Source Directory#

SETDIR "directory1/directory2"

This function is used together with the dynamic.conf to limit the hits search to just a part of the available directories.

The values of  are used by the dynamic.conf.

This variable is set also by READDIR, but READDIR physically searches the entire given directory and needs significantly more time. Example:

SETDIR "news/2001"

With this setting the variable contains  - news and  - 2001.

FILEMASK: Defining a Search Template#

FILEMASK = "regular expression"

The FILEMASK function is used to determine a search pattern. All files, whose name does not match the search pattern specified here, will be ignored. Example:

FILEMASK = ".*\.htm[lsx]?$"

This example finds all files which end with the suffix .htm, .html, .htms or .htmx.

SORT: Sorting a Hit List#

The hit list can be sorted alphabetically or numerically. By default, it is sorted alphabetically.

Sorting by Date#

In order to sort the hits by date, use the SORT LATEST FIRST, resp. SORT OLDEST FIRST, function.

## Most recent documents first:
SORT LATEST FIRST

## Oldest documents first:
SORT OLDEST FIRST

The SORT LATEST FIRST function sorts the newest hits in the beginning of a list, SORT OLDEST FIRST sorts the oldest hits in the beginning of a list. Further parameters are not necessary.

Sorting by Full Path#

With the SORT BY FILENAME function you sort the hit list by the full path of a file.

SORT BY FILENAME

If the path consists partially or entirely from continuous numbers, for example when using the  variable or time variables (e.g. __) in a directory name, the function can work very efficiently. Further parameters are not necessary.

Sorting by Path Components#

In order to sort the hit list by the integral parts of the path, you should use the SORT BY DIRELEM function. You can transfer two numeric values as parameters.

SORT BY DIRELEM "value1" TO "value2"

Sorting by Meta Variables#

With the SORT BY METAFIELD function the hit list is sorted by a particular meta variable.

SORT BY METAFIELD "meta variable name"

Example:

SORT BY METAFIELD "title"

This setting sorts the hit list alphabetically based on the title. It is also possible to use meta variables that have numerical values.

In order to sort hit lists by multiple meta variables, use the SORT BY MULTIFIELD function:
The following code is wrapped for representation purposes.

SORT BY MULTIFIELD "PREFIXmeta variable 1,PREFIXmeta variable 2,
  PREFIXmeta variable X"

The prefix is used to specify the expected content of the corresponding meta field. The following prefixes for multifield sorting are possible:

Prefix	Meaning
`#`	Use this prefix when the corresponding meta field contains numerical data and imperia should make a corresponding sorting.
`~`	The meta field includes ISO latin 1 data, which should be sorted without considering capital and small letters.
`!`	The meta field contains ISO latin 1 data. The sorting sequence should correspond to the collating sequence (usually ASCII sequence).
`+`	Ascending sort.
`-`	Descending sort.

The sorting sequence depends on the order of the specified meta fields.

RANDOM PICK: Random Hits#

RANDOM PICK
RANDOM PICK number

In order to let random hits from the hit list show, use the RANDOM PICK, resp. RANDOM PICK number, function.

The RANDOM PICK function shows arbitrary hits from the list. The number of the displayed hits can be additionally limited via a LIMIT HITS instruction.

You can specify the number or arbitrary hits to be displayed with the RANDOM PICK``number function.

LIMIT HITS: Limiting / Filtering Hit Lists#

Limiting a hit list indicates how many hits should be displayed. To assign multiple LIMIT instructions use logical AND.

Using both SORT and LIMIT HITS instructions, you can easily generate an overview page with the 10 most recent documents.

Restricting Hit Lists#

To limit the displayed hits use the following syntax:

LIMIT HITS number

The parameter number specifies the number of displayed hits in the finished document. Example:

LIMIT HITS 10

The number of displayed hits is limited to a maximum of 10.

Limiting a Hit List to a range#

If you want to limit a hit list to a range, use the following:

LIMIT HITS "value 1" TO "value 2"

The parameters should be two numerical values. The first is the beginning of the range, the second - the end. The further processing of a hit list is done only within this range.

Limiting a Hit List by a Meta Variable#

With the LIMIT BY function you can limit the number of displayed hits, dependent on one meta variable.

LIMIT BY meta variable "value 1" TO "value 2"
NOCASELIMIT BY meta variable"value 1" TO "value 2"

Along with a meta variable, you must indicate numeric marginal values. Example:

LIMIT BY limit "2" TO "5"

This example sets as a prerequisite the presence of a meta variable limit in the searched documents. The hit list displays only documents which have the values 2, 3, 4 or 5 in the meta variable limit.

To make the search case insensitive, use NOCASELIMIT.

REJECT: Excluding Specific Files#

You can exclude specific files from a hit list with the REJECT function.

REJECT "path"

The path of the files to be excluded is noticed in double quotation marks.

ALLOW: Clearing the Exception of Specific Files#

When you have excluded some documents with REJECT (see REJECT: Excluding Specific Files) from a hit list in a SiteActive block, you can clear the exclusion with ALLOW:

ALLOW "path"

You should indicate the path in double quotation marks.

FILTER: Filtering a Hit List#

FILTER "meta variable" CONTAINS "regular expression"

The keyword FILTER is used to define a filter for a hit list. The filter must be defined BEFORE the READDIR instruction. The behavior of a filter is defined by different operators. The following are available:

(NOT)CONTAINS
(NOT)SMALLER
(NOT)GREATER
(NOT)EQUALS

You can use regular expressions with the operators CONTAINS and NOTCONTAINS. (NOT)SMALLER and (NOT)GREATER are numeric comparisons. EQUALS and NOTEQUALS are case insensitive.

Note

Only the CONTAINS and NOTCONTAINS operators work with meta fields that have multiple values. All other commands expect a single value.

For further information read Example 3: Filtered Hit List.

Important

Defined limitations are not cleared after a SiteActive run. To clear them use the instruction CLEARLIST, resp. clearlist(), at the beginning of the next SiteActive block of instructions.

Functions for an Internal Hit List#

CLEARLIST: Clearing an Internal Hit List#

CLEARLIST

If you desire no transfer of hit lists and limitations from previous SiteActive blocks or runs, you must delete the internal hit list in the beginning of a SiteActive block, since otherwise the new block works with the found in previous blocks hits and the corresponding limitations. Use the instruction CLEARLIST.

Note

This function also deletes all restrictions from previous hit list (LIMIT HITS, LIMIT BY METAFIELD, etc.).

CLEARLIMIT: Removing Restrictions#

CLEARLIMIT

CLEARLIMIT deletes any restrictions from previous hit lists, but not the hit lists themselves.

REVERSE LIST: Reversing a Hit List#

You can sort a hit list by a defined meta variable with the SORT BY METAFIELD function.

SORT BY METAFIELD "meta variable name"

Example:

SORT BY METAFIELD "title"

This setting sorts the hit list by page title alphabetically. It is also possible to use meta variables which contain numeric values.

To reverse the sequence of hist use the REVERSE LIST function.

REVERSE LIST

This function is beneficial together with the following functions:

SORT BY FILENAME
SORT BY METAFIELD
SORT BY DIRELEM

To sort hit lists by multiple meta variables, use the SORT BY MULTIFIELD function:

SORT BY MULTIFIELD "PREFIXmeta variable 1,PREFIXmeta variable 2,PREFIXmeta variable X"

You can specify the expected content of the corresponding meta field with the prefix parameter. The following prefixes for multifield sortingare available:

Prefix	Meaning
`~`	The meta field includes ISO latin 1 data, which should be sorted without considering capital and small letters.
`+`	Ascending sort.
`-`	Descending sort.

The sorting sequence depends on the order of the specified meta fields.

IF LIST: Readout Depending on a Hit List's Length#

You can control the readout of text depending on a hit list's length. You can specify whether text should only be displayed when a hit list is greater or smaller than a specific value, resp. when it has a particular length. You can use the following syntax:

IF LIST GREATER X PRINT "More than X matches."
IF LIST SMALLER X PRINT "Less than X matches."
IF LIST EQUALS X PRINT "Exactly X matches."

X is a placeholder for the hit list's length. With the operators GREATER, SMALLER and EQUALS you control if a hit list should contain a number of hits greater, smaller or equal to the specified number.

PRINT: Text Output#

You can read out text when processing a SiteActive block with the PRINT function. You can use HTML tags to format the text output.

PRINT "Text"
PRINT 'Text'

Important

This function cannot be used within the FOREACH FOUND loop.

The readout text is noted in double or single quotation marks. Examples:

PRINT 'A list of <b>all</b> matches:'
PRINT "A list of <b>all</b> matches:"

DYNAMIC: Turning On and Off `dynamic.conf` Replacement#

Within a SiteActive block you can activate and deactivate additional replacement done by dynamic.conf.

## deactivate dynamic.conf:
DYNAMIC DISABLE

## activate dynamic.conf:
DYNAMIC ENABLE

FOREACH FOUND loop#

FOREACH FOUND loops can execute instructions for each relevant hit. The syntax is as follows:

FOREACH FOUND {
  instruction 1
  instruction 2
  instruction 3
   ...
}

In this way you can control the actual output of the SiteActive. The following example demonstrates how you can create a simple link list with a loop of the path, filename and title of the documents in a hit list:

FOREACH FOUND {
  <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a><br />
}

Another example:

FOREACH FOUND {
  <tr>
    <td bgcolor="#c0c0c0" height="10px">
      <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
    </td>
  </tr>
}

With these instructions the loop generates a table row for every hit.

IF Conditions in FOREACH FOUND Loops#

Within a FOREACH FOUND instruction you can test with IF conditions whether

a file is available or not,
a value is defined or is not,
two values are equal or not.

The syntax for an IF condition is as follows:

IF (NOT) EXISTS condition PRINT text
IF (NOT) DEFINED condition PRINT text
IF (NOT) EQUALS condition PRINT text

Examples:

FOREACH FOUND {
IF EXISTS "<!--YY-directory-->/teaser.html" PRINT
  <a href="<!--YY-directory-->/teaser.html"><!--YY-teaser--></a>
}

Important

The PRINT instruction is, in this case, an integral part of the IF EXISTS syntax and is not within the described PRINT: Text Output syntax.

The example tests if the file /teaser.html exists. If it exists, the content of the meta variable  is displayed.

To check if a file is available, use the following syntax:

FOREACH FOUND {
IF NOT EXISTS "<!--YY-directory-->/teaser.html"
PRINT "The file no longer exists."
}

The same syntax is valid for IF (NOT) DEFINED and IF (NOT) EQUALS.

PERLEVAL: Executing One-line Perl Code#

With this function you can execute a single line of Perl code, without using the Perl plug-in for SiteActive. The Perl code to be executed must be contained in a single line after the keyword PERLEVAL.

PERLEVAL Perl code

PERLEVAL also delivers the return value of the expression. If you use, for example, the function print the PERLEVAL should return 1 along with the text.

Example:

PERLEVAL "<!--YY-teaser-->" unless  ("<!--YY-teaser-->" eq "")

The content of the meta variable teaser of the corresponding document is displayed, as long as it is not empty.

Example for an IF condition in PERLEVAL:

<tr>
  PERLEVAL "<!--YY-topic-->" !~ /myTopic/ ? '<td class="green">'
  : '<td class="red">'
  <!--YY-titel-->
  </td>
</tr>

Important

Curved brackets must be escaped by a leading backslash.

If the value of the meta variable topic does not match the string myTopic, the string is displayed after the question mark. If the value and the string match, the string after the colon is displayed.

DISRUPT: Breaking FOREACH FOUND Loops#

DISRUPT EVERY number LINES BY text
DISRUPT END

With this function, you can always add text to the output of a FOREACH FOUND loop after a certain number of hits. This can be, for example, an HTML code, which loads an image or displays a horizontal line, with which the hit list is divided.

A DISRUPT instruction consists of an opening statement that contains the text to be inserted, and a closing statement. The opening statement must be in front of the keyword FOREACH FOUND and the closing statement - after the curved brackets, that close the FOREACH FOUND loop. Example:

DISRUPT EVERY 2 LINES BY <td bgcolor="#c0c0c0" height="10px">
&amp;nbsp;</td>
FOREACH FOUND {
  <tr>
    <td width="180">
      <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
      </td>
  </tr>
}
DISRUPT END

With this code the generated list is separated after every second entry by a colored table cell.

LOOPCOUNT: Number of Completed Loop Runs#

<!--LOOPCOUNT+start value-->

The number of completed loop runs is given in the variable . This variable requires a start value that is incremented by one after each FOREACH FOUND loop run. Example:

FOREACH FOUND {
Results <!--LOOPCOUNT+1--><br />
  <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title-->
  </a><br />
}

IACTIVE: Outsourcing SiteActive Code#

If you want to use the same SiteActive code in multiple overview pages, which differ only in a few parameters, it is a good idea to store the SiteActive code in an external file.

That file should be stored in one of the following two locations on a target system:

path/to/DOCUMENT-ROOT/FILENAME
path/to/Imperia site directory/activelist/FILENAME

To make SiteActive code available, add the following instructions at the place, where external content will later be displayed in a document:

<!--IACTIVE:FILENAME-->

Along with the name of the file with the SiteActive code, the FILENAME can also contain a path with a directory name. This is beneficial, for example, when you wish to place your external SiteActive file in an access protected directory in the document root.

Compared with the CODEINCLUDE instruction, IACTIVE has the advantage that code embedded this way can be used again at the same place, after a replacement is done. A CODEINCLUDE is simply replaced with code from an external file. Then, there is no more indication in the document that external components have been integrated at this point.

When you use IACTIVE, after the SiteActive expansion, the template looks as follows:

<!--IACTIVE:FILENAME-->
Content generated with SiteActive.
<!--/IACTIVE:FILENAME-->

If imperia finds this when executing a system service in a document, it will once more replace the references to the external SiteActive code and then expand it:

<!--IACTIVE:FILENAME-->
Content of file FILENAME.
<!--/IACTIVE:FILENAME-->

After that the instructions from the code block are interpreted. In this way a SiteActive template and a target file can physically be the same file.

Examples#

Copy the files in /site/sample/sa to /htdocs/sa.

/site/sample/sa/sa_news.htms - a multilingual SiteActive template based on documents generated by the news.html template. The imperia.schedule file has to be extended accordingly: lingua parameters {code}.
For presentation purposes the code is wrapped:

1300710298 DESCR="News EN" 1300710298:dayzone=daily:timezone1=00:timezone2=00:TEMPLATE=sa/sa_news.htms: SAVEPAGE=/news.html.en:lingua=en:VERIFY=/news
/site/sample/sa/sa_news_VIEWTEMPLATE.html - view template for a news overview.

SiteActives - Examples#

The following subchapter provides examples with the most used SiteActive functions. A description of all functions can be found in Syntax Reference.

The examples don't explain the layout of the readout. The layout can be adjusted in the generated HTML within the FOREACH FOUND loop with cascading stylesheets or similar techniques.

Note

You should make sure that these examples do not reach an actual target system on which your website is running to avoid damage to your project. We recommend to set up a test target system for the programming of the examples listed here.

Prerequisites#

All listed here examples need the following:

A SiteActive template which contains the SiteActive code and serves as layout pattern for the preview page to be generated.
A time or event driven system service. Refer also to chapter System Services of the administration documentation.
Documents from which the desired information can be read. This is done with YY variables, which can reference the corresponding meta variable of the found documents (see YY variables ).

Example 1: Simple Link List#

The path and title of each document are required so that imperia can build a link list. Both values are read by SiteActive using YY variables. The full path is generated from the values of the directory and filename meta variables. The link text should be generated from the title of a target document with the help of the meta variable title.

All documents that reside in or under the directory specified as READDIR are considered in this example. There is no limitation for the generated list.

In the generated HTML page, the links are separated by carriage returns. However, it is also possible to add a table row for every detected document within the FOREACH FOUND loop (see also Example 2).

A simple link list is generated as follows:

<IMPERIA>
  CLEARLIST 
  FILEMASK = ".*\.htm[lsx]?$" 
  READDIR = "/path/to/documents" 
  FOREACH FOUND { 
    <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a><br />
  }
</IMPERIA>

Deleter eventually available hit list and restrictions from a previous SiteActive block.
Regular expression that documents' filenames must match so that they are considered as hits.
Determines a directory to be searched recursively for matches.
This is the output routine. The entered in the oval brackets HTML code is generated for every hit in the HTML page. The YY variables are replaced by the corresponding values from the found documents.

Example 2: Restricted Link List#

This example uses the same information as example 1. The information is referenced again with YY variables.

For the hit list in this example there are two limitations, namely the number of the displayed links and the hit list sorting. The sorting ensures that the newest documents are listed in the beginning of the list, which must include maximum 25 documents.

A link list with limited length can be generated as follows:

<table>
  <IMPERIA>
    CLEARLIST 
    FILEMASK = ".*\.htm[lsx]?$"
    READDIR = "/path/to/documents" 
    SORT LATEST FIRST 
    LIMIT HITS 25  
    LIMIT BY limit_char "A" TO "E" 
    FOREACH FOUND { 
      <tr>
        <td>
          <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
        </td>
      </tr>
    }
  </IMPERIA>
</table>

Deletes eventually available hit list and restrictions from a previous SiteActive block.
Determines a directory to be searched recursively for matches.
Sorts a hit list, so that the newest documents are listed at the top.
Reduces the hit list to 25 entries.
Limits documents by the meta variable limit_char with value between “A” and “E”. You may also use the FILTER function (see FILTER: Filtering a Hit List).
The HTML code in the curved brackets is included for every hit in the generated HTML page and in this HTML code the YY variables are replaced by values from the found documents.

Example 3: Filtered Hit List#

Apart from the LIMIT function, you may use filters to limit a hit list. Such a filter must be defined before the READDIR command.

In order to generate a link list with documents which title starts with the letter “A” the following SiteActive code can be used:

<table>
  <IMPERIA>
    CLEARLIST
    FILEMASK = ".*\.htm[lsx]?$"
    FILTER "title" CONTAINS "^A" 
    READDIR = "/path/to/documents"
    SORT LATEST FIRST
    FOREACH FOUND {
      <tr>
        <td>
          <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
        </td>
      </tr>
    }
  </IMPERIA>
</table>

Defines the filter, so that only documents that have the meta variable title with a value that starts with the letter “A” are considered as hits. Use regular expressions.

Example 4: Simple Preview Page#

In this example a simple preview page is generated. It contains a documents title and a short teaser. The title serves as a link to the corresponding document.

Prerequisite for this exmaple is the presence of the following meta variables in the searched documents:

directory, filename, title
teaser

The title and teaser are placed in a table. In order to avoid making the preview page too long, the number of displayed hits is limited to ten and only the latest documents are considered.

<table>
  <IMPERIA>
    CLEARLIST
    FILEMASK = ".*\.htm[lsx]?$"
    READDIR = "/path/to/documents"
    SORT LATEST FIRST
    LIMIT HITS 10  
    FOREACH FOUND { 
      <tr>
        <td>
          <a href="<!--YY-directory-->/<!--YY-filename-->"><!--YY-title--></a>
        </td>
      </tr>
      <tr>
        <td>
          <!--YY-teaser-->
        </td>
      </tr>
      <tr>
        <td>&nbsp;</td>
      </tr>
    }
  </IMPERIA>
</table>

Reduces the hit list to ten entries.
The table is extended as follows for every detected document:
- a row with a linked title
- a row with a teaser text
- an empty row which serves as divider

Example 5: Simple Overview Page With Perl#

imperia uses a special Perl plug-in for SiteActives that already defines certain variables, hashes and lists. In particular, this is the list @FILELIST that contains all documents that have been recognized as hits by filemask() and ireaddir().

This example requires the existence of the following meta variables:

directory and filename (are automatically available in every document)
title
teaser

<table border="0" cellspacing="0" cellpadding="0">
<IMPERIA lang=perl> 
clearlist();
filemask('.*\.htm[lsx]?$');
ireaddir ('/path/to/documents');

foreach my $file (@FILELIST) {  
  my $directory = $FILE_META_INFO{$file}->getValues('directory'); 
  my $filename = $FILE_META_INFO{$file}->getValues('filename');

  my $title = $FILE_META_INFO{$file}->getValues('title');
  my $teaser = $FILE_META_INFO{$file}->getValues('teaser');

      print <<EOF; 
       <tr>
         <td><a href="$directory/$filename"><b>$title</b></a></td>
       </tr>
       <tr>
         <td>$teaser</td>
       </tr>
       <tr>
          <td> </td>
       </tr>
EOF
}
</IMPERIA>
</table>

The lang attribute of the IMPERIA tag should be set to perl in order to make imperia use Perl as the interpreter for SiteActive code.
In this loop, imperia iterates over all documents, contained in the @FILELIST list. The $file variable references the corresponding document path and filename on every iteration.
The meta variable directory is assigned to the Perl variable $directory. This is done with the hash $FILE_META_INFO that contains the meta information objects of the documents. The getValues() function takes the name of the desired meta variable of a document as an argument and stores it in the variable.
This is the output. The variables are automatically replaced with their value that is then copied to the output.

Example 6: Overview Page With Perl and Alternating Layout#

This example generates an overview page in which the layout is alternated with the help of a counter variable.


<IMPERIA lang=perl>
  clearlist();
  filemask('.*\.htm[lsx]?$');
  ireaddir ('/documents');
  my $count = 0; 

  foreach my $file (@FILELIST) {

    my $url = $FILE_META_INFO{$file}->getValues('directory') . '/' .
    $FILE_META_INFO{$file}->getValues('filename') ;
    my $image = $FILE_META_INFO{$file}->getValues('teaser_img');
    my $title =  $FILE_META_INFO{$file}->getValues('title');
    my $teaser = $FILE_META_INFO{$file}->getValues('teaser');

    if ($count++%2) { 
      print <<EOF;
        <tr>
          <td>
            <a href="$url"><b>$title</b></a><br/>
            $teaser
          </td>
          <td>
            <img src="$teaser_img">
          </td>
        </tr>
EOF

    } else {
      print <<EOF;
        <tr bgcolor="#cacaca">
          <td >
            <img src="$teaser_img">
          </td>
          <td>
            <a href="$url"><b>$title</b></a><br/>
            $teaser
          </td>
        </tr>
EOF
    }
  }
</IMPERIA>

Initializes a counter variable that controls the alternation of the layout.
Saves the relevant meta variables from the documents in Perl variables.

Note

Curved brackets must be escaped by a leading backslash.
Tests the counter variable $count. If the value of $count is divisible by two, the condition returns true and the first HTML code section is executed. If the condition returns false, the HTML code section of the else branch is used.

The two HTML output sections differ only in the arrangement of the image and the text.

Calling SiteActives Manually#

If SiteActives are executed for testing purposes during development, the triggering of the corresponding system service may be too complicated. It is also possible that you do not want to generate a file during the test run. In this case it is beneficial to manually invoke the SiteActive script. In this instance, you have to pass the parameters, which normally come from the configuration of the system service, as CGI parameters:

http://my.site.en/cgi-bin/site_active.pl?TEMPLATE=/siteactive/template.html

The invocation happens through the address bar of the browser or through a link. The result of the SiteActive is displayed directly in the browser window.

When you want to store the result of a manual SiteActive invocation to a file, you must additionally pass the parameter SAVEPAGE. For security reasons, imperia forbids manual SiteActive invocations that write files by default. You must therefore also provide a password. This password can be defined in the site/config/system.conf file with the SAVEPAGE-PASSWORD variable. Here is an example for a full invocation of a SiteActive from the address bar of a browser, including SAVEPAGE and password:

CODE WRAPPED FOR REPRESENTATION PURPOSES

http://my.site.de/cgi-bin/site_active.pl?TEMPLATE=/siteactive/template.html&
  SAVEPAGE=/dynamic/index.html&SAVEPAGE-PASSWORD=secret_password

Important

The directories, resp. the SiteActive template, which are transferred with the parameters TEMPLATE and SAVEPAGE, are under the root directory (document root).

Triggering Multiple System Services#

If you wish to create yearly, monthly, etc. news archives or paginated overview pages, you can use the parameter SAVEPAGES instead of SAVEPAGE. Example:

SAVEPAGES=/ssi/news/overview{PAGE}.html

This instruction calls the system service in a loop until the returned page is empty, contains only whitespace and/or HTML comments. Each invocation gets an extra PAGE parameter that has the values 0, 1, 2, etc.

When saved, the placeholder {PAGE} gets replaced by the parameter.

You can also call SAVEPAGES with extensions:

SAVEPAGES=/ssi/news/overview{PAGE+2012}.html

In this case the values of the {PAGE} parameter will be 2012, 2013, 2014, etc.

The operator (+ or -) is optional. The default is +.

Furthermore, you can limit the creation of pages, using the MAXPAGES parameter. The default value is 99.

SmartMeta#

With SmartMeta you have the possibility to assign meta variables depending on the values of other meta variables. This function is controlled by the /site/config/smart-meta.conf file. This file must be available on every system, on which you wish to use SmartMeta with SiteActives.

The value assignments concern only generated with SiteActive documents. The source documents from the hit list remain unchanged.

Note

The workflow plug-in with the same name uses the same functionality (see SmartMeta in the administration documentation). Variable assignments performed by this plug-in, can be defined in the smart-meta.conf file.

As soon as a corresponding configuration file is available, SiteActive automatically checks if the conditions defined there are fulfilled during the page generation, and then executes them depending on the check's result. The testing and processing of the meta information of a SiteActive document with SmartMeta are done first. Then, the SiteActive instructions are executed.

Configuring SmartMeta#

Every line of smart-meta.conf contains two meta variable name and value pairs. The left pair defines the meta variable which operates as test criterium for the value assignment, as well as the condition, in which this happens. The right pair defines the meta variable to be changed and the value to be assigned. The meta field's name and value are divided by =>. Here is an example of the syntax:

meta variable 1 = value 1 => meta variable 2 = value 2

With this instruction Meta Variable 2 is assigned value 2, when Meta Variable 1 has value1.

You can also make multiple value assignments at the same time:

meta variable 1 = value 1 => meta variable 2 = value 2
                   => meta variable 3 = value 3
                   => meta variable 4 = value 4

Further examples and explanations can be found in the site/config/smart-meta.conf file.

SiteActive with imperia Views#

With the conversion of imperia 9 to the Model-View-Controller paradigm some features that were previously only for documents can now be transferred to imperia views. In this chapter, it is explained how to include documents, parts of documents and meta information within imperia views, using SiteActive. All the features you know from SiteActive, have been transferred, but called with a new syntax.

SiteActive Views Call#

To call SiteActives from your imperia views, use either the Import or Postimport directive:

{% ##import('SiteActive') %}

{% ##postimport('SiteActive') %}

Make sure that {SITE-ACTIVE} is added in the definition of the System Service before the path to the SiteActive template that is to be found under site/active/default/ and is developed in the Impperia-View language.
Example from the file imperia.schedule:

    TEMPLATE={SITE_ACTIVE}imperia.net/solutions/all.html:SAVEPAGE=/ssi/solutions/

In case the SiteActive template is under htdocs, you can also define it this way:

    TEMPLATE={DOCUMENT_ROOT}/imperia.net/solutions/all.html:SAVEPAGE=/ssi/so ...

Wenn das Template unterhalb von htdocs ist.

Important

This module cannot be executed in other Perl templates.

Recursive Document Search with ireaddir()#

Using ireaddir(arguments), you search recursively for documents, managed by imperia. This function is equivalent to the READDIR function in the old SiteActive syntax (see READDIR: Defining a Source Directory). The function can be called in a simple and an extended version. In the simple version, the path to the directory to be searched is passed to the function:

{%entries = ireaddir (['/news/sports']);%}

When the function is called with no arguments, it searches from the root directory.

In the extended version, with several arguments, the function expects its arguments in a hash. The following arguments can be passed:

directory
A list of one or more directories (default is "/").

startlevel
The recurcive search starts from this level (default is 0).

maxdepth
Defines a maximum depth for the recursive search (default is 0).

reject
Excludes a path from the search; it can be a file or a directory.

allow
One or more paths to a directory or file, previously excluded with reject.

filemask
The search returns only documents that match the REGEX filter (default value is '\ htm').

Example Document Search with `ireaddir()`#

Let's assume the following directory structure:

http://localhost/articles/info/index.html.en
http://localhost/articles/about/003095/index.html.en
http://localhost/articles/news/2009/003113/index.html.en
http://localhost/articles/news/2009/003113/index.html.de
http://localhost/articles/news/2010/003126/index.html.en
http://localhost/articles/news/2010/003126/index.html.de
http://localhost/articles/news/2011/003141/index.html.en
http://localhost/articles/news/2011/003141/index.html.de

SiteActive call in a View template:

{%
    lingua = 'en';    /* params.lingua // 'en'; */
    entries = ireaddir(
                directory => ['/articles/news'],
                startlevel => 3, maxdepth => 4,
                reject => ['/articles/about', '/articles/news/2011',
                           '/articles/news/2009/003113/index.html.en'],
                allow => ['/articles/news/2011/003141/index.html.en'],
                filemask => concat('^index\\.html\\.', lingua, '$')
               );
%}

The search returns the following URLs:

/articles/news/2010/003126/index.html.en
/articles/news/2011/003141/index.html.en

Document Search with `fireaddir()`#

fireaddir(arguments) functions in the same way as ireaddir(), but the search is not recursive.

Document Search with GLOB Syntax#

Using the glob ([pattern ...]) function, you search a directory for documents by specifying a list of directory filters. The filter syntax uses GLOB syntax, which is used in the UNIX Shell.

Example Document Search with GLOB#

Let's assume the following directory structure:

http://localhost/articles/news/2010/003129/index.html.en
http://localhost/articles/news/2010/003129/index.html.de
http://localhost/articles/news/2010/003126/index.html.en
http://localhost/articles/news/2010/003126/index.html.de

SiteActive call in a View template:

{%
  entries = glob(["/articles/news/2010/?????9/*.en",
                 "/articles/news/2010/*6/index.html.de"]);
%}

The search returns the following URLs:

/articles/news/2010/003129/index.html.en
/articles/news/2010/003126/index.html.de

Sorting the Results with `sort()`#

You may sort a hit list, using the sort() function. The sorting can be defined using the parameters below.

by_uri
Results are sorted alphanumerically by path and file name. This function is equivalent to SORT BY FILENAME in the old SiteActive syntax (see Sorting by Full Path).

SiteActive call in a View template:

{%
  entries = ireaddir (['/news/sports']);
  entries = sort (entries, 'latest_first');
%}

latest_first
Results are sorted by the last modification time. Most recently edited documents are displayed on top of the list. This function is equivalent to SORT LATEST FIRST in the old SiteActive syntax (see Sorting by Date).

SiteActive call in a View template:

{%
  entries = ireaddir (['/news/sports']);
  entries = sort (entries, 'latest_first');
%}

oldest_first
Results are sorted by the last modification time. Oldest documents are displayed on top of the list. This function is equivalent to SORT OLDEST FIRST in the old SiteActive syntax (see Sorting by Date).

SiteActive call in a View template:

{%
  entries = ireaddir (['/news/sports']);
  entries = sort (entries, 'oldest_first');
%}

by_meta
Results are sorted by a meta field. By default, the sort is alphanumerical. However, using modifiers, this behavior can be changed. One or more meta variables can be used to sort results.

Optionally, you may change the sorting rules, using one or more modifiers, placed as prefixes to the meta field.

prefix	description
+	Descending order (default)
-	Ascending order
#	Numerical sorting
!	Reverse order

SiteActive call in a View template:

{%
  entries = ireaddir(['/news/sports']);

  entries = sort(entries, 'by_meta', 'filename');
  entries = sort(entries, 'by_meta', 'directory, filename');
  entries = sort(entries, 'by_meta', ['directory', 'filename']);

  lingua = 'en';    /* params.lingua // 'en'; */
  entries = sort(entries, 'by_meta', concat('title_', lingua));

  entries = sort(entries, 'by_meta', ['#__imperia_last_uid', '-!filename']);
  entries = sort(entries, 'by_meta', '-!title, -#__expiry_time');

%}

by_direlem
Results are sorted by the directory structure or parts of it. Each directory in the path, separated by “/”, defines an element of the sequence. To restrict the sorting to parts of the directory's path, use the arguments START and END, where START is the starting level and END is the last level.

SiteActive call in a View template:

{%
   entries = sort(entries, 'by_direlem');
   entries = sort(entries, 'by_direlem', 1, 2);
%}

Filtering Results with `filemask()`#

You can filter a hit list with a regular expression in Perl syntax. This function is equivalent to FILEMASK in the old SiteActive syntax (see FILEMASK: Defining a Search Template).

SiteActive call in a View template:

{% entries = filemask(entries, '^index\\.html$') %}
{% entries = filemask(entries, '\'') %}

Important

Backslashes and single quotes must be escaped!

Limiting Results with `limit()`#

You can limit a hit list to a given number. The limitation depends on the sort order of the documents. This function is equivalent to LIMIT in the old SiteActive syntax (see LIMIT HITS: Limiting / Filtering Hit Lists).

SiteActive call in a View template:

{% entries = limit (entries, 10) %}

Important

Backslashes and single quotes must be escaped!

Siteactive

Procedure and Components of the SiteActive#

Prerequisites#

System Service#

Notification#

SiteActive Templates#

Maintaining SiteActive Templates with imperia#

Managing SiteActive Templates without imperia#

Syntax Reference#

IMPERIA: Including SiteActive Instructions#

READDIR: Defining a Source Directory#

SETDIR: Defining Source Directory#

FILEMASK: Defining a Search Template#

SORT: Sorting a Hit List#

Sorting by Date#

Sorting by Full Path#

Sorting by Path Components#

Sorting by Meta Variables#

RANDOM PICK: Random Hits#

LIMIT HITS: Limiting / Filtering Hit Lists#

Restricting Hit Lists#

Limiting a Hit List to a range#

Limiting a Hit List by a Meta Variable#

REJECT: Excluding Specific Files#

ALLOW: Clearing the Exception of Specific Files#

FILTER: Filtering a Hit List#

Functions for an Internal Hit List#

CLEARLIST: Clearing an Internal Hit List#

CLEARLIMIT: Removing Restrictions#

REVERSE LIST: Reversing a Hit List#

IF LIST: Readout Depending on a Hit List's Length#

PRINT: Text Output#

DYNAMIC: Turning On and Off dynamic.conf Replacement#

FOREACH FOUND loop#

IF Conditions in FOREACH FOUND Loops#

PERLEVAL: Executing One-line Perl Code#

DISRUPT: Breaking FOREACH FOUND Loops#

LOOPCOUNT: Number of Completed Loop Runs#

IACTIVE: Outsourcing SiteActive Code#

Examples#

SiteActives - Examples#

Prerequisites#

Example 1: Simple Link List#

Example 2: Restricted Link List#

Example 3: Filtered Hit List#

Example 4: Simple Preview Page#

Example 5: Simple Overview Page With Perl#

Example 6: Overview Page With Perl and Alternating Layout#

Calling SiteActives Manually#

Triggering Multiple System Services#

SmartMeta#

Configuring SmartMeta#

SiteActive with imperia Views#

SiteActive Views Call#

Recursive Document Search with ireaddir()#

Example Document Search with ireaddir()#

Document Search with fireaddir()#

Document Search with GLOB Syntax#

Example Document Search with GLOB#

Sorting the Results with sort()#

Filtering Results with filemask()#

Limiting Results with limit()#

DYNAMIC: Turning On and Off `dynamic.conf` Replacement#

Example Document Search with `ireaddir()`#

Document Search with `fireaddir()`#

Sorting the Results with `sort()`#

Filtering Results with `filemask()`#

Limiting Results with `limit()`#