[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
The following tags are always available in any template or a template part.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following params are always available in any template or a template part.
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> - _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="->" 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] | [ ? ] |
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.
unsafe
characters) replaced
by their hexadecimal form. This is suitable for insertion in the URL part
of an a tag, for instance.
SQL editor configuration file
.
SQL editor configuration file
.
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.
SQL editor configuration file
.
SQL editor configuration file
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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> ... |
... <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.
Within the entry part, the following tags are defined.
_DEFAULTROW_
was not found in the
template, See section Database table tags
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
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 --> |
List of hidden fields necessary to perform the search. Must
be included in each form
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |