Introduction

General Features#

Imperia Views is the standard internal templating system for the Imperia CMS. It is used to render the HTML pages of the Imperia GUI but it is designed to be usable in other applications as well. It perfectly blends into an MVC (Model View Controller) approach to web applications. The system features

  • intuitive syntax,
  • comfortable skinning features,
  • high performance by aggressive caching strategies and lazy evaluation
  • modular design and extensibility.

Whereas the regular Imperia template processor allows both a WYSIWIG approach to structured document editing and document rendering, the focus of Imperia Views is clearly on high-performance rendering. The interface for extensions to the systems has been designed with the interests of several players in the game in mind. The players are in order of precedence

  1. system administrators without any background in HTML, design or programming, that want to do simple customizations to the system,
  2. designers whose task it is to skin the system to the specific needs of their organization,
  3. programmers who want to adapt or extend the Imperia GUI,
  4. programmers who want to extend the templating system itself.

The more interest in the design of the system can be assumed, the more expertise is expected.

Quick Start#

CGI Script For Testing#

It is easier for you, if you test the template engine at first stand-alone, without any special Imperia stuff. Please drop the following script as viewtest.pl in your CGI-BIN directory:

#! /usr/local/bin/perl -w
use strict;
BEGIN {
push @INC, $1 if $0 =~ m#(.*)[\\\/]#;
}
use site_lowlevel;
use Imperia;
my $parser = $imperia->viewParser;
$parser->setDirectories('/tmp/myviews');
my $data = {
common => {
title => 'Test Page for Imperia Views',
system_conf => { %SYSTEM_CONF },
template => 'gips.net',
},
hash_example => {
foo => 0,
bar => 1,
baz => 3,
},
array_test => [ 13, 3, 66 ],
};
print "Content-Type: text/html; charset=utf-8\n\n";
print $parser->parse('test.html')->render($data);

You don't have to understand the details of this script.

Next create a file /tmp/myviews/mytest.html, with some arbitrary content.

Now log into Imperia, and then point your browser to http://your.webserver.here/cgi-bin/viewtest.pl. You should see the content of your template file unchanged. The rest of this document tells you how to play with the system, and see some meaningful output.

Please put all your templates in the directory /tmp/myviews or subdirectories of it, so that the system can find them.

Includes#

Like most other template engines, the Imperia view processor, does nothing more than replacing certain tags in template files:

<html>
<head>{% #include('head.html') %}</head>
<body>{% #include('body.html',
use_javascript => 'y') %}</body>
</html>

You will have guessed already, that the processor will replace the tags of the format {% ...%} with something, and leave the rest of the file untouched. In this case, it will replace the tags with the content of the included files. In fact, this will not be the raw content of the included file, but instead, the included data is first processed. That means, that your include structure can be arbitrarily nested.

The above example also shows, that you can pass variables to the included files.

Interpolations#

You can interpolate the value of variables into the output:

<h1>{% title %}</head>

If the first relevant character inside of {% ... %} is not a hash sign (“#”), the content is treated as a variable interpolation. If the value of the variable contains one of the XML special characters (“<”, “>”, “&”, “'”, or “"”) they are replaced by the corresponding HTML entities. If you want to avoid that, you can use the function raw():

<div>{% raw(generated_div) %}</div>

In fact, this behavior is special to the way the template processor is used in Imperia. If you dig deepter into things, you will find out that it is at the discretion of the implementor, whether a final filter is applied to interpolations, and which filter this is. Likewise, the concept of which functions are considered “safe” is subject to local implementation. It is not necessarily the function raw(). Actually, also in Imperia a number of functions are considered “safe” as well, for example escape_html() and escape_js().

Variables#

Variables, that you can interpolate can be arbitrarily nested data structures: 

<h1>{% common.titles.my_script %}</h1>

If parts of the structure happen to be Perl objects, you can even call methods with parameters on them:

Logged in as {% common.user.getInfo('name') %}

If you don't know the name of a certain part in your structure beforehand, you can use a different syntax. The above example could also be expressed like this:

{% something = 'user' %}
Logged in as {% common[something].getInfo('name') %}

Now, inside of the angle brackets, the variable something is first evaluated, and then the result is used for dereferencing.

Skinability#

When including files, the Imperia view processor does not look for these files in a fixed location, but uses a search path instead. In the files that are generated for the Imperia GUI, the default is the path SITE-DIR/view/imperia/default. But you can override this by the system.conf variable IMPVIEW_INCLUDE:

"IMPVIEW_INCLUDE" = "/etc/local_ci, imperia/default"

Now the system first searches files underneath the path /etc/local_ci, and then in imperia/default. Paths that start with a slash are considered absolute, otherwise they are resolved relative to the directory SITE-DIR/view. This allows you to replace only certain templates, and you still will not lose your ability to upgrade the system.

In our little example, we have hard-coded the directory search list instead.

Inside Imperia, if you upgrade your system, and the installer detects that a template file that you have customized was modified in that upgrade, the installer will issue a warning, so that you have a chance to apply the necessary changes to your local templates.