The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-BuildPage-0.95
++
/ CGI::BuildPage

NAME

CGI::BuildPage - object to hold and build page

SYNOPSIS

        use CGI::BuildPage;
        my $q = new CGI::BuildPage();

and then it's similar to CGI.pm, but use add instead of prints.

MOTIVATION

During the development of the Administrative server of our faculty we found out that certain parts of our scripts are typed again and again. This included such things like background color or image settings, links that should go with icons and logos, creating two column pages, etc. So even if we were using CGI.pm to parse the parameters and create the HTML answer, there still was a big deal of duplicate "static" code in our scripts.

That's why we designed a interface that is in part presented here as the CGI::BuildPage module. It inherits from CGI, so it has the same capabilities and methods, with one main exception: the methods like startform or textfield do not return the HTML code produced but store it inside of the object. That's why the module can also add certain visual elements to the proper places of pages, like logos and signatures, and can produce two column output using tables.

One of the requirement we had on the module was a support of different styles for different parts of our organization. The visual part of the HTML document is to great extend described using a set of rules in the module and you can make the script produce different page by only a change of parameters to the method layout. You can even have one script, linked from more directories, that checks the path_info() and prints answers with different layouts.

Another features include the possibility to check parameters for "strange" characters, logging of the script execution including the parameters, modification of the HTTP headers at any time during the script processing.

The module allows the authors of the scripts (and we have more than 250 on our Web site) to concentrate on the real goals of the script, like getting the parameters, checking them, fetching data from files or database and building the parts of the output page as you go or changing the expire date or cache pragma depending on the results.

The module uses tables to create the layout. Even if new techniques are emerging, we need a tool giving results that will be understood by even old browsers. HTML seems to be the language of choice for now and at least a year to come.

DESCRIPTION

The list of methods available in CGI::BuildPage follows. Note that only the changes from the CGI's behavior or new methods are listed here.

Basic methods and building HTML

new

Creates the basic object, calls CGI::new. If the first parameter is the word 'no_log', doesn't log the script execution. This can be used for unimportant script where the logging in Apache's access_log is enough, or for scripts that take passwords as their parameters. We can alter or remove the password parameter and then log explicitely using log_in:

        my $query = new CGI::FI('no_log');
        my $passwd = $query->param('password');
        $query->param('passwd', crypt (...salt etc...));
        ### or directly $query->delete('passwd');
        $query->log_in();
layout

Specify the layout and institution, for which we produce the page. This method should be called before we start to add things into the page. The distribution module supports layout values plain, white, narrow and wide, institution values blue and green.

add

Adds the parameter to the content of the page. It doesn't print it out, stores it into the object instead. Example:

        $query->add('<H2>Enter your code</H2>');

If the layout is two column, adds to the right (main) column.

add_left, add_both

Adds to the left column or to both (using COLSPAN). If the layout doesn't imply two columns, adds to the main, possibly doing some more formatting.

All these three adding methods append the newline character to the parameter by default. This can be switched off by specifying word 'no_lf' as the first parameter. Left column is typeset top-justified, it can be centered using 'vcenter' as another optional word at the start of parameter list.

flush

Flushes the columns, the global line in the two column layout. You can thus mix add and add_left and they will be appended to the their columns independently.

Actually print the content of the HTML answer to the output. You can give parameters to this method, then this data will be printed instead of the accumulated content. This can be handy for dynamic gifs, generated using GD, for example.

The HTML producing methods of CGI are changed so that they store their result into the content in the object, using add. One exception is the method hr, which depends on the layout of the page and may return a picture, and also stores using add_both.

sign

Specifies the signature of the page, instead of the default one. The second parameter will be used in the mailto HREF.

add_icon

Adds user defined icons to the line of default icons. The parameters are: picture file, alternate text and the HREF.

Other parameter methods

no_cache, allow_cache

Specifies whether to send the No-cache HTTP header, default yes.

no_header, allow_header

Switches off and on sending the HTTP headers. This can be used for caching the output of the CGI into html file. Default is allow.

expires

Sets the expire date, the format is the same as in CGI.

https_keysize

Returns the length of the keys in HTTPS protocol, 0 for plain HTTP.

check_input_params

Checks if the parameters contain "unsecure" characters, meaning possible hacker attack. The names of the parameters are the arguments. If a problem is found, logs error and send an email to the root.

Errors, logging

To log in explicitely, use method log_in. To log error, use log_error, optionally giving it one character symbol of the error.

The method bad_parameter can be used to abort the script execution.

Method REPORT is used to email the message to the root (note that similar functionality is provided by the module Tie::STDERR, so this could also be done via use Tie::STDERR and print STDERR).

VERSION

0.95

SEE ALSO

perl(1), CGI(3).

AUTHOR

(c) 1998 Jan Pazdziora, adelton@fi.muni.cz, http://www.fi.muni.cz/~adelton/ at Faculty of Informatics, Masaryk University in Brno, Czech Republic