Templates

• Custom modules
• Server-Side Includes (SSI)
• HTML::Template

Custom Modules

• Perl provides two mechanisms for code reuse:
  • Libraries
  • Modules or packages
• Modules provide way of defining separate namespaces
  • All scripts have at least a main namespace
• Namespaces used to avoid that variable and subroutine names defined in different libraries overlap
• Modules are declared in files with a .pm extension
  • Module CGI defined in CGI.pm
  • Module HTML::Template defined in HTML/Template.pm
• Typically stored in a system-wide path, but can also be defined relative to your script
• To use a module, include it via the use operator

  use CGI::Carp;
  use HTML::Template;

Defining a Custom Module

• To define a module Some::Module, create a file Some/Module.pm
• Start the file with a package declaration

  package Some::Module;

• In a package constructor, initialize the package:
  • Set the version
  • Declare the package symbols to be exported (i.e. made visible to the main package)
  • Specify initialization code
• The remainder of the file defines the subroutines you are exporting, as well as helper routines
• Return a true value at the end of the file

Defining a Custom Module (Example)

• The following module defines a subroutine for handling errors (CS205/Error.pm)

  package CS205::Error;
  
  use CGI;
  use CGI::Carp qw( fatalsToBrowser );
  
  BEGIN {
  	# Set the version for version checking
  	$VERSION = "0.1";
  	
  	# Export the error subroutine
  	use Exporter;
  	@ISA = "Exporter";
  
  	@EXPORT = qw( error );
  
  	sub handleError {
  		my $message = shift;
  		my $q = new CGI;
  		error($q, $message);
  	}
  	CGI::Carp::set_message( \&handleError );
  }
  
  sub error {
  	my ($q, $message) = @_;
  	print $q->header("text/html"),
  		$q->start_html("Error"),
  		$q->h1("Error"),
  		$q->p("An error has occurred:"),
  		$q->p($q->em($message)),
  		$q->end_html;
  	exit;
  }
  
  1;

Using the module

• Here is an example of how our module can be used:

  use CGI;
  use CS205::Error;
  
  my $q = new CGI;
  
  unless ($q->param("action")) {
  	error($q, "No action specified");
  }
  
  print $q->header("text/html");
  print "action = ", $q->param("action");

Templates

• Web page design and CGI script development involve very different skills
  • Web page design is the concern of visual designers and UI specialists
  • CGI script development is very technical in nature
• Need to separate interface from program logic
  • Applications require maintenance
  • Making changes to an HTML file is generally easier than modifying a CGI script
  • More people understand HTML than Perl
  • It should be possible to change wording and layout of web pages without changes to the CGI script

Server-Side Includes (SSI)

• Suitable for web pages that require small amounts of dynamic data
• SSI allows you to embed directives in HTML documents to execute other programs or insert data
• For example, the following line inserts the last date of modification into a web page

  Last modified: <!--#echo var="LAST_MODIFIED"-->

• Syntax:

  <!--#command attribute="value" ... -->

• HTML files with SSI commands have the extension .shtml

Server-Side Includes

• Browser requests a document with SSI comands
• Server parses document and replaces SSI commands with their result in the document

  

Inserting Environment Variables

• You can insert the values of environment variables into an HTML document
• Syntax of the echo command:

  <!--#echo var="var_name"-->

• Examples:

  Dear user from host <!--#echo var="REMOTE_HOST"-->
  Last modified: <!--#echo var="LAST_MODIFIED"-->

• Some SSI-specific environment variables are availabe (e.g. DOCUMENT_URI)

Including Files

• Some information is repated in many documents
• You can include one file that has the information into several other documents
• Syntax of the include command:

  <!--#include file="footer.html"-->
  <!--#include virtual="/~user/includes/footer.html"-->

• The first form only allows relative file names, whereas the second form can specify an absolute URL
• Example:

  <html>
  <head><title>ACME Ltd. Newsletter</title></head>
  <body>
  <table>
  <tr>
    <td colspan="2">
      <!--#include virtual="header.html"-->
  <tr>
    <td>
      <!--#include virtual="navbar.html"-->
    <td>
      <!--#include virtual="main.html"-->
  <tr>
    <td colspan="2">
      <!--#include virtual="footer.html"-->
  </table>
  </body>
  </html>

• See the output

Executing CGI Programs

• Another typical use of SSI is to include the results of a CGI script into a document
• This can be achieved either using exec or include virtual
• Syntax of the include virtual command:

  This page has been accessed
  <!--#include virtual="/cgi/counter.cgi"--> times.

• This only works if enabled on the server

HTML::Template

• SSI has limitations
  • Simple enough to be used by non-programmers
  • Limited commands and only parses static documents
• HTML::Template addresses these issues
  • At the core of HTML::Template are variable tags embedded into a template file

HTML::Template (Example)

• The following is an example of a simple template that will display the current time

  <html>
  <head><title>Current Time</title></head>
  <body>
    <h1>Current Time</h1>
    Welcome. The current time is <tmpl_var name="time">.
  </body>
  </html>

• This template contains a non-HTML tag TMPL_VAR that will be substituted by the value of the variable "time"

HTML::Template (Example)

• Script that uses this template

  use HTML::Template;
  
  # open the template file
  my $template = new HTML::Template( filename => 'current-time.tmpl' );
  
  # get local time
  my $time = localtime();
  
  # fill in the template parameters
  $template->param( time => $time );
  
  # print the content-type
  print "Content-Type: text/html\n\n";
  
  # print the template
  print $template->output;

• See the output

Commands

• TMPL_VAR
  Replaced by value of parameter

  <tmpl_var name="paramName">

• TMPL_LOOP
  Iterates over content for each item in an array

  <tmpl_loop name="paramName">
      ...
  </tmpl_loop>

• TMPL_IF
  Includes content if value of parameter is true

  <tmpl_if name="paramName">
      ...
  </tmpl_if>

• TMPL_INCLUDE
  Includes contents of another file

  <tmpl_include name="file/path">

Loops

• One of most interesting features is to create loops

• Argument to TMPL_LOOP must be an array of hashes
  • Iterates over each element in the array
  • Creates variables corresponding to the hash keys

Loops (Example)

• Template for displaying a list of profiles in a table

  <html>
  <head><title>Profile Viewer</title></head>
  <body>
    <h1>Profile Viewer</h1>
    <hr>
    <table border cellpadding="4" width="400">
      <tmpl_loop name="profiles">
        <tr>
          <td><tmpl_var name="name">
          <td><tmpl_var name="location">
          <td><tmpl_var name="age">
        </tr>
      </tmpl_loop>
    </table>
  </body>
  </html>

Loops (Example)

• A sample list of profiles

  

Loops (Example)

• This script will display all profiles in the list

  use HTML::Template;
  
  # open the template file
  my $template = new HTML::Template( filename => 'loops.tmpl' );
  
  # set the table data
  my @profiles = (
    { name     => "Bob",
      location => "Ottawa",
      age      => 33 },
    { name     => "Alice",
      location => "Toronto",
      age      => 25 },
    { name     => "Mary",
      location => "Montreal",
      age      => 21 },
  );
  
  # fill in the template parameters
  $template->param( profiles => \@profiles );
  
  # print the content-type
  print "Content-Type: text/html\n\n";
  
  # print the template
  print $template->output;

• See the output

Conditionals

• Two ways to create a conditional:
  • TMPL_IF and TMPL_UNLESS
• Used to include or omit portions of a template
  • Parameter is evaluated in a boolean context
  • Perl evaluation rules (empty string = false)

  <table>
  
  <tmpl_loop name="results">
  <tr>
    <td><tmpl_var name="title">
    <td><a href="<tmpl_var name="url">"><tmpl_var name="url"></a>
  </tmpl_loop>
  
  <tmpl_unless name="results">
  <tr>
    <td colspan="2">No titles match your query
  </tmpl_unless>
  
  </table>

Install HTML::Template

• HTML::Template is one of the many modules that can be downloaded from http://www.cpan.org

• Download URL:

  http://search.cpan.org/search?module=HTML::Template

• Unzipping results in a directory:

  HTML-Template-2.2

• Copy Template.pm to HTML folder relative to your script

  HTML/Template.pm

• Extract the documentation:

  pod2html --infile Template.pm --outfile Template.html

References

• Apache module mod_include which supports SSI

Reading

• For next class read Chapter 10 on "Data Persistence" in CGI Programming in Perl
• We will cover chapters on JavaScript and Security after that