[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Template files introduction

The template files are the HTML files used by the cgi-bin to interact with the user. Every interaction step is associated with the file name of a template, the content of this file is read and analyzed by the cgi-bin and portions of it are replaced according to the action taken.

The simplest of all templates is the error template. It looks like this:

 
<title>Error</title>
<center><h3>
Error<p>
_MESSAGE_
</center></h3>

When an error occurs in a cgi-bin the error template is used. The _MESSAGE_ tag is replaced by the actual error message and the result is sent to the user.

The templates file names are located in the current directory if the TEMPLATESDIR environment variable is not set. If it is set it must contain a list of colon separated directories. The directories are explored in order to find the template file. If no file is found a default in-core version is used.

A template is often divided is parts, sometimes recursively. The general syntax of this subdivision is as follows:

 
bla bla...
<!-- start part -->
bla bla...
<!-- start subpart -->
bla bla...
<!-- end subpart -->
bla bla...
<!-- end part -->
bla bla...

The template contains a part named part. This part contains a subpart named subpart. This kind of subdivision is used when a component of the template must be repeated or conditionally included. Note that the specifications for parts are included in HTML comments to prevent interferences when editing the template with a wysiwyg editor.

Within a part, it is possible to specify arbitrary parameters to the cgi-bin using the params specification.

 
<!-- params 'var1' => 'value1', 'var2' => 'value2'... -->

The exact variables allowed in such an instruction and the interpretation of their values depend on the cgi-bin.

The tags of a template are strings that will be replaced by actual values by the cgi-bin. The tags are always surrounded by underscores and the strings are in upper case. If two strings appear in the same tag they are separated by a dash (-). These are valid tags:

These are not valid tags:

The tags found in a part or subpart of a template may be the same, this does not mean that they will be replaced by the same string. All the parts and subparts have a separate name space. Always refer to the template documentation to find out which tags are defined.

The exact semantic associated to these subdivisions completely depends on the action associated to the template.

10.1 Templates switch table  
10.2 Fixed tags  
10.3 Fixed params  
10.4 Database table tags  database table tags
10.5 Record list part  
10.6 Multipage results template  
10.7 Server side includes  
10.8 Actions that takes a long time  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.1 Templates switch table

In order to allow multiple template files to coexist, the template package configuration file allows arbitrary mapping of the template file names listed in this chapter to other file names, See section Template configuration file. The choice of a specific name map depend on the style parameter, See section Style parameter.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.2 Fixed tags

The following tags are always available in any template or a template part.

`_SCRIPT_'
Absolute path of the cgi-bin script (/cgi-bin/Catalog for instance). It may be used to set the action part of a FORM HTML tag.

`_HTMLPATH_'
Absolute location of the Catalog HTML material (/Catalog for instance). It contains the documentation, examples and an images subdirectory (/Catalog/images for instance).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.3 Fixed params

The following params are always available in any template or a template part.

`pre_fill'
Name of, or reference to, a function to call before filling in the corresponding part of a template. The function can return a reference to a modified deep-copy of the template hash.

`post_fill'
Name of, or reference to, a function to call after filling in the corresponding part of a template. The function can return a modified copy of the expanded HTML.

Here's an example:

 
	<!-- start entry -->
	<!-- params pre_fill => \&MyCat::pre_fill_entry, post_fill => \&MyCat::post_fill_entry -->
	<LI><a href='_URL-QUOTED_'>_URL_</a> &nbsp;- _DESCRIPTION_ <!-- _COUNT_ -->
	<!-- end entry -->

The MyCat::pre_fill_entry will be called with two parameters: a reference to the template hash and a reference to an array of 'parent' templates, which may be empty. The function must at least return the template hash reference. Note that you should always modify a deep-copy of the template and not the original because changes to the original will be permenant within mod_perl.

The MyCat::post_fill_entry will be called with three parameters: the first two are the same as for pre_fill_entry. The third is the generated HTML. The function must return an HTML string. Here's an example that adds an arrow gif for symbolic links:

 
    package MyCat;
    use Catalog;
    @ISA = qw(Catalog);

    MyCatalog->selector();

    sub post_fill_entry {
	my ($template, $parents, $html) = @_;
	return $html if @$parents > 0; # needed for mysterious reasons
	my $a = $T->{assoc};
	if ($a->{_COUNT_} && $a->{_COUNT_} eq "@") {
	    $html .= q{<IMG SRC="_SCRIPT_/../images/arrow.png" ALT="-&gt;" WIDTH="19" HEIGHT="8">};
	}
	return $html;
    }

Note that in order for _COUNT_ to be in the $template->{assoc} hash, it must appear within the template. If you don't want _COUNT_ to appear in the output then put it inside an HTML comment, as shown above.

At the moment there is no direct way for the functions to access the current Catalog CGI object. You could replace the C<selector()> call in the example above with calls to:

 
    my $self = MyCat->new();
    $self->selector();
    $self->close();
    undef $self;

The pre_fill and post_fill functions could then refer to $self.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.4 Database table tags

Most templates display fields from tables and they all follow the same conventions. If the template documentation states that a record from table table is available in a specific part of the template, a set of tags is automatically available.

`_FIELDNAME_'
The value of the field, verbatim. As a special case, if the field is of type blob, and img tag is generated to display the content of the field. It must be a GIF file.

`_FIELDNAME-QUOTED_'
The value of the field, with all characters that would cause problems in HTML (quote, double quote, lower than and greater than) replaced by their symbolic form. This is suitable for insertion in the value part of an input tag, for instance.

`_FIELDNAME-CODED_'
The value of the field, with all characters that would cause problems in an URL (space, ampersand and all so called unsafe characters) replaced by their hexadecimal form. This is suitable for insertion in the URL part of an a tag, for instance.

`_FIELDNAME-MENU_'
Only suitable for fields of type set or enum. Display the current value of the field within a select style menu listing all the allowable values of the field. If the type of the field is set, the menu generated allows multiple selection. The exact display generated depends on the definitions found in the sqledit.conf file, See section SQL editor configuration file.

`_FIELDNAME-RADIO_'
Only suitable for fields of type enum. Display the current value of the field within a table of radio buttons. The radio button associated with the current value is checked. The exact display generated depends on the definitions found in the sqledit.conf file, See section SQL editor configuration file.

`_FIELDNAME-CHECKBOX_'
Only suitable for fields of type set. Display the current values of the field within a table of checkboxes. The check boxes associated with the current values is checked. The exact display generated depends on the definitions found in the sqledit.conf file, See section SQL editor configuration file.

The tags listed above may be prefixed by the name of the table to disambiguate.

This form is only necessary if to tables have the same field name and a part of the template provide a record from both of them.

Each datatype has a default display form that is used when nothing is specified in the template. Here is an association between the MySQL datatypes and the default display associated with them.

`char of size 1'
Input text of size two.
`char of size > 30 and < 1000'
Input text of size thirty.
`char of size > 1000'
Text area of six rows and thirty columns.
`integer'
Input text of size ten.
`date or time'
Input text of size twenty.
`blob'
File upload.
`set'
Table of checkboxes, See section SQL editor configuration file.
`enum'
Single choice menu, See section SQL editor configuration file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.5 Record list part

In many templates there are template parts (see the introduction at the beginning of this chapter) used to display a list of records from the database. All of them (with the notable exception of the query by example search result, See section sqledit_search.html.) use the same library and comply to the following part description for their display.

`Params and Parts'

If there is a style parameter in the enclosing part and that the value associated with this parameter is table, then the part used to display the search results will be row. Otherwise the part used will be entry.

`style = {table,vtable}'
Use row part. The columns parameter is the number of columns generated. For each record, the entry part is repeated. If the entry part has been repeated columns times, the row part is displayed with the generated entries.

If style value is table the columns are ordered horizontaly, if style value is vtable the columns are ordered verticaly.

 
...
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> <a href='_URL_'>_NAME_</a> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
...

`style = *'
Use entry part, repeated as many times as there are records.

 
...
<ul>
<!-- start entry -->
<li> <a href='_URL_'>_NAME_</a> (_COUNT_)
<!-- end entry -->
</ul>
...

If no records are found, the row or entry parts are not displayed.

In some cases, the entry part (within a row part or stand alone) may be subdivided as shown below:

 
...
<ul>
<!-- start entry -->

<!-- start company -->
<li> _COMPANY-NAME_ _COMPANY_URL_
<!-- end company -->

<!-- start customer -->
<li> _CUSTOMER-NAME_ _CUSTOMER-ACTIVITY_
<!-- end customer -->

<!-- end entry -->
</ul>
...

This subdivision is always an alternative, that is, either the company part or the customer part will be displayed, never both. This is mainly used to specify a part that many contain records from different tables so that they are displayed in a specific way. The exact semantic associated with these subparts is defined by the cgi-bin.

`Tags'

Within the entry part, the following tags are defined.

`table tags'
All the automatically generated tags for the database table are available, provided that _DEFAULTROW_ was not found in the template, See section Database table tags.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.6 Multipage results template

All the cgi-bin that want to display their result using more than one HTML page use the same module to implement this functionality. For instance, when searching the database, the first page displayed only contains the first ten results. A footer is added to the page with links to the next pages. The default footer looks like this:

images/pager

The footer is called the pager section. In the example it shows the total number of pages on one line. The next line shows the current page as a page number not associated with a link. All other page numbers are associated with a link that gives direct access to the page.

If no pager template part is found, the display is automatically switched to a one page display. Here is an example pager part :

 
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->

`_MAXPAGES_'
Is the total number of pages available.

`_PAGES_'
Is a fixed format list of links that give direct access to the first twenty pages and indirect access to the others, as shown in the example output above.

List of hidden fields necessary to perform the search. Must be included in each form.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.7 Server side includes

A limited support of the server side include syntax is provided in the template files. If an include instruction is found, the cgi expands it. For instance:

 
<!--#include virtual="/dir/file.html" -->

will be expanded with the content of the file found at $DOCUMENT_ROOT/dir/file.html. This is done again and again until no more include instruction is found, allowing nested inclusions. Note that the tag substitution is done before expanding the included file. Therefore, no tag substitution will occur in the included files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.8 Actions that takes a long time

Some cgi-bin actions may take a very long time, such as catalog loading or dumping. When an action is likely to take a long time, the cgi-bin emits white space characters from time to time to provide a user feedback. When the action begins a blank page is shown to the user and the status bar of the navigator shows that some characters are received.

This feedback serves two purposes : it shows that the action is doing something and keeps the connection alive so that the HTTP server does not timeout.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on November, 18 2003 using texi2html