NAME

CGI::Template - An easy to use and intuitive template system for Perl web application development.

SYNOPSIS

  use CGI::Template;
  my $t = new CGI::Template;

  ...

  print $t->header();
  print $t->content(
     PLACEHOLDER  => $value,
     PLACEHOLDER2 => $value2,
     ...
  );

DESCRIPTION

CGI::Template simplifies and speeds up the development of web applications by providing an easy to use system that inherently keeps web design and code separate.

Each time a script that uses CGI::Template is executed, CGI::Template will automatically grab the appropriate template, and then replace any placeholders with their new values and finally output the finished page.

Furthermore, CGI::Template provides an easy error-handling system with the error() method.

EXPORT

None by default.

SETUP

Directory Structure

The easiest way to get started with CGI::Template is to create a new directory within your cgi-bin directory called templates.

Template Files

Create a new HTML file within the templates directory called default.html containing your site design. Any text within the template that will need to be filled in by CGI scripts should be replaced with placeholders.

Create a second HTML file within the templates directory called error.html containing the template for your application's error messages. This HTML file must contain a placeholder titled MESSAGE.

Placeholders

A placeholder is designated within a template by beginning with the characters #! and ending with the characters !#. For example:

  #!PLACEHOLDER!#

It is convention to use all caps for placeholder names. No spaces may be used within placeholder names. Additionally, a placeholder may be used multiple times within a template.

CGI Scripts

Any CGI script using CGI::Template will now output the content of default.html. If a script needs a different template, then simply create a new HTML file within the templates directory with the same name as the CGI script. For instance, if you are using the script cgi-bin/search then its template would be cgi-bin/templates/search.html.

Note that CGI::Template disregards extensions of CGI scripts. Therefore, search.cgi or search.pl would also use the templates/search.html template.

METHODS

new()

The constructor method for CGI::Template. Options are passed in key/value pairs. The following key/value pairs are recognized:

doctype

Specifies the DOCTYPE to use for the document. Possible values are: none, html5, strict, frameset, or transitional. If no doctype is specified, the html5 doctype is used.

templates

Sets the path to the templates directory. By default this is a directory called templates under the directory from which the script is being executed (typically cgi-bin).

request

Specifies the request method to be used. Possible values are get or post. If set, CGI::Template will require that all requests to the script be of the type specified. Any other types of requests will result in a call to error().

$t->header()

Returns an HTTP Content-type header. By default, the mimetype returned is text/html but this can be specified. header() accepts options in the form of key/value pairs:

-content-type

Sets the MIME type value in the header. Some examples:

  print $t->header( -content-type => "image/png" );
  print $t->header( -content-type => "text/plain" );

-redirect

Causes header() to return a HTTP Location header that will redirect the user to a new page. Example:

  print $t->header( -redirect => "/cgi-bin/new_location" );

-cookie

Sets a cookie. Example:

  print $t->header( -cookie => $cookie );

[any other key]

Any other key passed will result in the addition of the key and value to the header. Example:

  print $t->header( Expires => $date );

will result in:

  Content-type: text/html
  Expires: [date specifed]

$t->content()

Returns the final HTML output. Accepts placehoders and their replacements as key/value pairs. These replacements will be made throughout the current template. Example:

If CGI::Template is called from a script called "welcome":

  #!/usr/bin/perl -w
  use strict;

  use CGI::Template;
  my $t = new CGI::Template;

  my $title = "Welcome";
  my $menu  = "Menu";
  my $text  = "Hello world.";

  print $t->header();
  print $t->content(
     TITLE => $title,
     MENU  => $menu,
     TEXT  => $text,
  );

And the contents of cgi-bin/templates/welcome.html are as follows:

  <html>
    <head>
       <title>#!TITLE!#</title>
    </head> 
    <body>
       <div id="menu">#!MENU!#</div>
       <div id="content">#!TEXT!#</div>
    </body>
  </html>

Then the resulting output of the "welcome" script will be:

  Content-type: text/html

  <!DOCTYPE html>
  <html>
    <head>
       <title>Welcome</title>
    </head> 
    <body>
       <div id="menu">Menu</div>
       <div id="content">Hello world.</div>
    </body>
  </html>

$t->get_template()

Requres a string argument. Returns a template retrieved from the file named $string within the CGI::Template directory. This is useful to reduce the amount of time spent editing template content that is used on many pages throughout your web application. Example:

  my $menu = $t->get_template( "menu" );
  ...
  print $t->content(
      ...
      MENU => $menu,
      ...
  );

$t->replace_template()

Requires a string argument. Replaces the current template with the provided string argument. This is useful if under some conditions your script needs to output a different template than usual. Often used with get_template(). Example:

  if( $other ){
     my $new_template = $t->get_template( "other" );
     $t->replace_template( $new_template );

     print $t->header();
     print $t->content(
        PLACEHOLDER => $value,
        ...
     );
     exit;

  }

$t->path()

Returns the remaining content after the script name in the URL. (i.e., the content of the environment variable PATH_INFO).

$t->error()

Requres a string argument. Prints an HTTP header, an error message, and calls exit(). Accepts a string argument which then replaces the placehoder MESSAGE in the error template: error.html Example:

  $t->error( "Zip code must be numeric." ) if( $zipcode !~ /^\d+$/ );

SEE ALSO

There are many other HTML template systems available for Perl, and each one does things a little (or a lot) differently. If you'd like to freely mix Perl within your HTML you should check out HTML::Embperl. If you'd like to be able to process loops and such within HTML code, check out HTML::Template.

AUTHOR

David J. Venable, <davidjvenable@gmail.com>, @davevenable

COPYRIGHT AND LICENSE

Copyright (C) 2013 by David J. Venable

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.

cpanm CGI::Template

perl -MCPAN -e shell
install CGI::Template