CleanCode Perl Libraries
Multi-Lingual Library Maintainability
available: Perl not available: Java not available: JavaScript not available: Certified
not available: Testable
not available: Standalone
available: Diagnostic


CGI::PageGenerator - Dynamic web-page generator.


  use CGI::PageGenerator;
  $libMgr = CGI::PageValidator::LibraryMgr->new(...);
  $sequencer = CGI::PageSequencer->new(...);
  $verify = CGI::PageValidator->new(...);
  $fatalError = !($sequencer->success() && $libMgr->success());
  $verify->process() unless $fatalError;
  $genPage = CGI::PageGenerator->new(
      $inputOptions, $libMgr, $sequencer, $verify->errors(), $fatalError);
  print Data::Diagnostic->output($cgi->header().$genPage->output());
  print $genPage->output();


Perl5.005, HTML::Template, Data::Diagnostic


This module generates a dynamic web page based on: a data library manager which defines the data definitions, a page sequencer which specifies the page layout and page linkages, and an optional list of validation errors to enumerate. The web page includes front-end input validation. That is, once the user enters data and clicks to submit the data, a JavaScript validation engine will parse and validate the input, displaying any validation exceptions to the user in whatever fashion you designate.

The generated web page may be passed back to a client browser as a dynamic web page. Alternately, this module may be used in a standalone mode to generate a set of static web pages during a system build.

The utility program uses the object library associated with PageGenerator to create a page. Furthermore, this utility is a full-fledged navigation engine, in that data passed back from a client will go through back-end input validation, and, depending on the validation result, either the page will be re-generated with errors listed, or the follow-on page will be generated,

From the command-line, may be invoked, for example, as:

  perl DIAG_LEVEL=0x38 \
    PATH_INFO=/contact/GetInfo OUTPUT_DIAG=9 OUTPUT_ERR=9 > reportPage.htm

The PATH_INFO parameter selects a sequence and a page from the PageSequencer. The sequencer provides the page layout for data defined by the LibraryMgr, which is validated by the PageValidator engine. The above example assumes that your configuration file defines these diagnostics:


That command, then, will display on the console and record in the log file the diagnostic output of CGI::PageValidator, CGI::PageGenerator, and CGI::PageSequencer, as well as any errors.


A template file is an HTML file containing certain place-holder elements for dynamically generated data. The place-holders are filled in via HTML::Template protocols. HTML::Template uses XML/HTML-like constructs including:

<TMPL_LOOP loopName> ... </TMPL_LOOP>

<TMPL_IF conditionalName> ... </TMPL_IF>

<TMPL_VAR varName>


CleanCode comes with master templates -- skeleton.thtml and fatalError.thtml. Each of these includes subordinate building blocks, which are also templates. Several of these subordinate templates are mentioned in the next section. Typically you should start with the included templates; copy and modify them to fit your site's layout and look-and-feel requirements, leaving the HTML::Template constructs where they are. For a brief peek under the hood, though, see the Place Holders section.

Building Blocks

While you could create a single template containing place holders for your web page, it is more modular to create a template file for each logical chunk. These template-chunks may then be used as building blocks to create a complete template. Consider: any web page broadly includes the HTML elements head and body. To avoid overloading terms, and to conform to common semantics, we'll refer to these as the preamble, which is not visible on the page, and the text, which is all the visible material. The text typically contains the header, the body, and the footer. On a form-based web page, the body may be further subdivided into the opening text, the form, the buttons, and the closing text. On a CleanCode-generated web form page, the opening text includes validation errors; the closing text includes controls and diagnostics.

Keeping the above approach in mind, you may then specify a different template file for each web page in your sequence configuration file, where each template file referred to is not much more than a series of TMPL_INCLUDE directives specifying the building blocks to use. This provides for a high-degree of reusability and low code duplication. As an example, the following shows the complete basic template used by CleanCode.

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    <TMPL_INCLUDE headElement.thtml>
    <TMPL_INCLUDE header.thtml>
    <TMPL_INCLUDE validationErrors.thtml>
    <form method="POST" action="<TMPL_VAR formUrl>"
      <TMPL_INCLUDE fields.thtml>
      <TMPL_INCLUDE links.thtml>
      <TMPL_INCLUDE controls.thtml>
    <TMPL_INCLUDE diagnostic.thtml>
    <TMPL_INCLUDE footer.thtml>

Place Holders

The list of place-holder elements is shown below. You only need to include the ones you wish to show up on your web page.

pageTitle (TMPL_VAR)

To populate the HTML <title> element.

formUrl (TMPL_VAR)

To populate the action attribute of an HTML <form> element.

generator (TMPL_VAR)

To populate the content attribute of an HTML <meta> element (typically with name="generator").

diagnostic (TMPL_VAR)

A boolean if you wish to handle diagnostic output manually.

errors (TMPL_LOOP)

This element displays a list of error messages passed in to the object constructor as $errList. The following loop variables are required:

errMsg -- represents a string containing an error message to display.

See the CleanCode template file validationErrors.thtml.

fields (TMPL_LOOP)

This element displays a list of form fields, (specified via the PageSequencer object supplied to the constructor). The following loop variables are required:

fieldName -- used for programmatic reference.

The following loop variables are optional:

fieldElement -- a block of HTML code implementing the field.

fieldValue -- value of fieldName

displayName -- name of the field to show the user.

invalidMsg -- the default error message to load for the field.

skipValidate -- boolean indicating whether validation section should be omitted

See the CleanCode template files fields.thtml and viewfields.thtml.

This element displays a list of form links, typically buttons (specified via the CGI::PageSequencer object supplied to the constructor). The following loop variables are required:

linkName -- display name of the button.

The following loop variables are optional:

validate -- boolean indicating to invoke the client-side form validator.

linkHref -- URL that this link will invoke

See the CleanCode template file links.thtml.



PACKAGE->new(settings, libMgr, sequencer, errList, errorPage)

Returns a newly created object, a generator for web pages. The generator will create a page for the current node of the sequencer passed in, using the cgi and libMgr.


settings - an InputOptions object;

libMgr - a LibraryMgr object

sequencer - a PageSequencer object

errList - reference to array of strings

errorPage - boolean specifying generation of error page or normal page


a newly created object




Returns a generated web page based on the constructor arguments.


string representing a complete web page (not including the HTTP header).




Michael Sorens


$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $


CleanCode 0.9


CGI::PageSequencer, CGI::PageValidator


Hey! The above document had some coding errors, which are explained below:

Around line 314:

=back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR section

Around line 377:

=back doesn't take any parameters, but you said =back -- end of METHOD section

CleanCode Perl Libraries Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 Get CleanCode at Fast, secure and Free Open Source software downloads