Difference between revisions of "TemplateAnatomy"

From SoylentNews
Jump to: navigation, search
 
(One intermediate revision by one other user not shown)
Line 117: Line 117:
 
man Template\:\:Tutorial\:\:Web will get you this
 
man Template\:\:Tutorial\:\:Web will get you this
  
<H1>Template::Tutorial::Web</H1>
+
Some of these including the template tutorial listed top of this page, with wiki pages.
Section: User Contributed Perl Documentation (3)<BR>Updated: 2013-07-23<BR><A HREF="#index">Index</A>
 
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
 
  
 
+
[[Category:Development]]
-----------------------------------------------------------------------
 
 
 
 
 
 
 
 
 
<A NAME="lbAB">&nbsp;</A>
 
<H3>NAME</H3>
 
 
 
Template::Tutorial::Web - Generating Web Content Using the Template Toolkit
 
<A NAME="lbAC">&nbsp;</A>
 
<H3>Overview</H3>
 
 
 
<A NAME="ixAAC"></A>
 
This tutorial document provides a introduction to the Template Toolkit and
 
demonstrates some of the typical ways it may be used for generating web
 
content. It covers the generation of static pages from templates using the
 
tpage and ttree scripts
 
and then goes on to show dynamic content generation using <FONT SIZE="-1">CGI</FONT> scripts and
 
Apache/mod_perl handlers.
 
<P>
 
 
 
Various features of the Template Toolkit are introduced and described briefly
 
and explained by use of example. For further information, see Template,
 
Template::Manual and the various sections within it. e.g
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    perldoc Template                    # Template.pm module usage
 
    perldoc Template::Manual            # index to manual
 
    perldoc Template::Manual::Config    # e.g. configuration options
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The documentation is also available in <FONT SIZE="-1">HTML</FONT> format to read online, or download
 
from the Template Toolkit web site:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    <A HREF="http://template-toolkit.org/docs/">http://template-toolkit.org/docs/</A>
 
 
 
</PRE>
 
 
 
 
 
<A NAME="lbAD">&nbsp;</A>
 
<H3>Introduction</H3>
 
 
 
<A NAME="ixAAD"></A>
 
The Template Toolkit is a set of Perl modules which collectively
 
implement a template processing system.
 
<P>
 
 
 
A template is a text document with special markup tags embedded in it.
 
By default, the Template Toolkit uses '<TT>&quot;[%&quot;</TT>' and '<TT>&quot;%]&quot;</TT>' to denote
 
the start and end of a tag.  Here's an example:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% INCLUDE header %]
 
   
 
    People of [% planet %], your attention please.
 
   
 
    This is [% captain %] of the
 
    Galactic Hyperspace Planning Council.
 
   
 
    As you will no doubt be aware, the plans
 
    for development of the outlying regions
 
    of the Galaxy require the building of a
 
    hyperspatial express route through your
 
    star system, and regrettably your planet
 
    is one of those scheduled for destruction.
 
   
 
    The process will take slightly less than
 
    [% time %].
 
   
 
    Thank you.
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Tags can contain simple <I>variables</I> (like <TT>&quot;planet&quot;</TT> and <TT>&quot;captain&quot;</TT>) and more
 
complex <I>directives</I> that start with an upper case keyword (like <TT>&quot;INCLUDE&quot;</TT>).
 
A directive is an instruction that tells the template processor to perform
 
some action, like processing another template (<TT>&quot;header&quot;</TT> and <TT>&quot;footer&quot;</TT> in this
 
example) and inserting the output into the current template. In fact, the
 
simple variables we mentioned are actually <TT>&quot;GET&quot;</TT> directives, but the <TT>&quot;GET&quot;</TT>
 
keyword is optional.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    People of [% planet %], your attention please.      # short form
 
    People of [% GET planet %], your attention please.  # long form
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Other directives include <TT>&quot;SET&quot;</TT> to set a variable value (the <TT>&quot;SET&quot;</TT> keyword is
 
also optional), <TT>&quot;FOREACH&quot;</TT> to iterate through a list of values, and <TT>&quot;IF&quot;</TT>,
 
<TT>&quot;UNLESS&quot;</TT>, <TT>&quot;ELSIF&quot;</TT> and <TT>&quot;ELSE&quot;</TT> to declare conditional blocks.
 
<P>
 
 
 
The Template Toolkit processes all <I>text</I> files equally, regardless of what
 
kind of content they contain.  So you can use <FONT SIZE="-1">TT</FONT> to generate <FONT SIZE="-1">HTML</FONT>, <FONT SIZE="-1">XML</FONT>, <FONT SIZE="-1">CSS</FONT>,
 
Javascript, Perl, <FONT SIZE="-1">RTF</FONT>, LaTeX, or any other text-based format.  In this tutorial,
 
however, we'll be concentrating on generating <FONT SIZE="-1">HTML</FONT> for web pages.
 
<A NAME="lbAE">&nbsp;</A>
 
<H2>Generating Static Web Content</H2>
 
 
 
<A NAME="ixAAE"></A>
 
Here's an example of a template used to generate an <FONT SIZE="-1">HTML</FONT> document.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [%  INCLUDE header
 
          title = 'This is an HTML example';
 
       
 
        pages = [
 
          { url  = '<A HREF="http://foo.org'">http://foo.org'</A>
 
            title = 'The Foo Organisation'
 
          }
 
          { url  = '<A HREF="http://bar.org'">http://bar.org'</A>
 
            title = 'The Bar Organisation'
 
          }
 
        ]
 
    %]
 
      &lt;h1&gt;Some Interesting Links&lt;/h1&gt;
 
      &lt;ul&gt;
 
    [%  FOREACH page IN pages %]
 
        &lt;li&gt;&lt;a href=&quot;[% page.url %]&quot;&gt;[% page.title %]&lt;/a&gt;
 
    [%  END %]
 
      &lt;/ul&gt;
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
This example shows how the <TT>&quot;INCLUDE&quot;</TT> directive is used to load and process
 
separate '<TT>&quot;header&quot;</TT>' and '<TT>&quot;footer&quot;</TT>' template files, including the output in
 
the current document.  These files might look something like this:
 
<P>
 
 
 
header:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    &lt;html&gt;
 
      &lt;head&gt;
 
        &lt;title&gt;[% title %]&lt;/title&gt;
 
      &lt;/head&gt;
 
      &lt;body&gt;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
footer:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
        &lt;div class=&quot;copyright&quot;&gt;
 
          &amp;copy; Copyright 2007 Arthur Dent
 
        &lt;/div&gt;
 
      &lt;/body&gt;
 
    &lt;/html&gt;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The example also uses the <TT>&quot;FOREACH&quot;</TT> directive to iterate through the
 
'<TT>&quot;pages&quot;</TT>' list to build a table of links. In this example, we have defined
 
this list within the template to contain a number of hash references, each
 
containing a '<TT>&quot;url&quot;</TT>' and '<TT>&quot;title&quot;</TT>' member. The <TT>&quot;FOREACH&quot;</TT> directive iterates
 
through the list, aliasing '<TT>&quot;page&quot;</TT>' to each item (in this case, hash array
 
references). The <TT>&quot;[% page.url %]&quot;</TT> and <TT>&quot;[% page.title %]&quot;</TT> directives then
 
access the individual values in the hash arrays and insert them into the
 
document.
 
<A NAME="lbAF">&nbsp;</A>
 
<H4>Using tpage</H4>
 
 
 
<A NAME="ixAAF"></A>
 
Having created a template file we can now process it to generate some real
 
output. The quickest and easiest way to do this is to use the
 
tpage script. This is provided as part of the
 
Template Toolkit and should be installed in your usual Perl bin directory.
 
<P>
 
 
 
Assuming you saved your template file as <I>example.html</I>, you would run
 
the command:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    $ tpage example.html
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
This will process the template file, sending the output to <TT>&quot;STDOUT&quot;</TT> (i.e.
 
whizzing past you on the screen). You may want to redirect the output to a
 
file but be careful not to specify the same name as the template file, or
 
you'll overwrite it. You may want to use one prefix for your templates (e.g.
 
'<TT>&quot;.tt&quot;</TT>') and another (e.g. '<TT>&quot;.html&quot;</TT>') for the output files.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    $ tpage example.tt &gt; example.html
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Or you can redirect the output to another directory. e.g.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    $ tpage templates/example.tt &gt; html/example.html
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The output generated would look like this:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    &lt;html&gt;
 
      &lt;head&gt;
 
        &lt;title&gt;This is an HTML example&lt;/title&gt;
 
      &lt;/head&gt;
 
      &lt;body&gt;
 
        &lt;h1&gt;Some Interesting Links&lt;/h1&gt;
 
        &lt;ul&gt;
 
          &lt;li&gt;&lt;a href=&quot;<A HREF="http://foo.org">http://foo.org</A>&quot;&gt;The Foo Organsiation&lt;/a&gt;
 
          &lt;li&gt;&lt;a href=&quot;<A HREF="http://bar.org">http://bar.org</A>&quot;&gt;The Bar Organsiation&lt;/a&gt;
 
        &lt;/ul&gt;
 
        &lt;div class=&quot;copyright&quot;&gt;
 
          &amp;copy; Copyright 2007 Arthur Dent
 
        &lt;/div&gt;
 
      &lt;/body&gt;
 
    &lt;/html&gt;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The <I>header</I> and <I>footer</I> template files have been included (assuming
 
you created them and they're in the current directory) and the link data
 
has been built into an <FONT SIZE="-1">HTML</FONT> list.
 
<A NAME="lbAG">&nbsp;</A>
 
<H4>Using ttree</H4>
 
 
 
<A NAME="ixAAG"></A>
 
The tpage script gives you a simple and easy way to
 
process a single template without having to write any Perl code. The
 
&lt;ttree:Template::Tools::ttree&gt; script, also distributed as part of the
 
Template Toolkit, provides a more flexible way to process a number of template
 
documents in one go.
 
<P>
 
 
 
The first time you run the script, it will ask you if it should create a
 
configuration file (<I>.ttreerc</I>) in your home directory. Answer <TT>&quot;y&quot;</TT> to have
 
it create the file.
 
<P>
 
 
 
The &lt;ttree:Template::Tools::ttree&gt; documentation describes how you can change
 
the location of this file and also explains the syntax and meaning of the
 
various options in the file. Comments are written to the sample configuration
 
file which should also help.
 
<P>
 
 
 
In brief, the configuration file describes the directories in which template
 
files are to be found (<TT>&quot;src&quot;</TT>), where the corresponding output should be
 
written to (<TT>&quot;dest&quot;</TT>), and any other directories (<TT>&quot;lib&quot;</TT>) that may contain
 
template files that you plan to <TT>&quot;INCLUDE&quot;</TT> into your source documents. You can
 
also specify processing options (such as <TT>&quot;verbose&quot;</TT> and <TT>&quot;recurse&quot;</TT>) and provide
 
regular expression to match files that you don't want to process (<TT>&quot;ignore&quot;</TT>,
 
<TT>&quot;accept&quot;</TT>)&gt; or should be copied instead of being processed as templates (<TT>&quot;copy&quot;</TT>).
 
<P>
 
 
 
An example <I>.ttreerc</I> file is shown here:
 
<P>
 
 
 
<TT>$HOME</TT>/.ttreerc:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    verbose
 
    recurse
 
   
 
    # this is where I keep other ttree config files
 
    cfg = ~/.ttree
 
   
 
    src  = ~/websrc/src
 
    lib  = ~/websrc/lib
 
    dest = ~/public_html/test
 
   
 
    ignore = \b(CVS|RCS)\b
 
    ignore = ^#
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
You can create many different configuration files and store them
 
in the directory specified in the <TT>&quot;cfg&quot;</TT> option, shown above.  You then
 
add the <TT>&quot;-f filename&quot;</TT> option to <TT>&quot;ttree&quot;</TT> to have it read that file.
 
<P>
 
 
 
When you run the script, it compares all the files in the <TT>&quot;src&quot;</TT> directory
 
(including those in sub-directories if the <TT>&quot;recurse&quot;</TT> option is set), with
 
those in the <TT>&quot;dest&quot;</TT> directory.  If the destination file doesn't exist or
 
has an earlier modification time than the corresponding source file, then
 
the source will be processed with the output written to the destination
 
file.  The <TT>&quot;-a&quot;</TT> option forces all files to be processed, regardless of
 
modification times.
 
<P>
 
 
 
The script <I>doesn't</I> process any of the files in the <TT>&quot;lib&quot;</TT> directory, but it
 
does add it to the <TT>&quot;INCLUDE_PATH&quot;</TT> for the template processor so that it can
 
locate these files via an <TT>&quot;INCLUDE&quot;</TT>, <TT>&quot;PROCESS&quot;</TT> or <TT>&quot;WRAPPER&quot;</TT> directive.
 
Thus, the <TT>&quot;lib&quot;</TT> directory is an excellent place to keep template elements
 
such as header, footers, etc., that aren't complete documents in their own
 
right.
 
<P>
 
 
 
You can also specify various Template Toolkit options from the configuration
 
file. Consult the ttree documentation and help
 
summary (<TT>&quot;ttree -h&quot;</TT>) for full details. e.g.
 
<P>
 
 
 
<TT>$HOME</TT>/.ttreerc:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    pre_process = config
 
    interpolate
 
    post_chomp
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The <TT>&quot;pre_process&quot;</TT> option allows you to specify a template file which
 
should be processed before each file.  Unsurprisingly, there's also a
 
<TT>&quot;post_process&quot;</TT> option to add a template after each file.  In the
 
fragment above, we have specified that the <TT>&quot;config&quot;</TT> template should be
 
used as a prefix template.  We can create this file in the <TT>&quot;lib&quot;</TT>
 
directory and use it to define some common variables, including those
 
web page links we defined earlier and might want to re-use in other
 
templates.  We could also include an <FONT SIZE="-1">HTML</FONT> header, title, or menu bar
 
in this file which would then be prepended to each and every template
 
file, but for now we'll keep all that in a separate <TT>&quot;header&quot;</TT> file.
 
<P>
 
 
 
<TT>$lib</TT>/config:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% root    = '~/abw'
 
      home    = &quot;$root/index.html&quot;
 
      images  = &quot;$root/images&quot;
 
      email    = '<A HREF="mailto:abw@wardley.org">abw@wardley.org</A>'
 
      graphics = 1
 
      webpages = [
 
        { url =&gt; '<A HREF="http://foo.org',">http://foo.org',</A> title =&gt; 'The Foo Organsiation' }
 
        { url =&gt; '<A HREF="http://bar.org',">http://bar.org',</A> title =&gt; 'The Bar Organsiation' }
 
      ]
 
    %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Assuming you've created or copied the <TT>&quot;header&quot;</TT> and <TT>&quot;footer&quot;</TT> files from the
 
earlier example into your <TT>&quot;lib&quot;</TT> directory, you can now start to create
 
web pages like the following in your <TT>&quot;src&quot;</TT> directory and process them
 
with <TT>&quot;ttree&quot;</TT>.
 
<P>
 
 
 
<TT>$src</TT>/newpage.html:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% INCLUDE header
 
      title = 'Another Template Toolkit Test Page'
 
    %]
 
   
 
        &lt;a href=&quot;[% home %]&quot;&gt;Home&lt;/a&gt;
 
        &lt;a href=&quot;mailto:[% email %]&quot;&gt;Email&lt;/a&gt;
 
   
 
    [% IF graphics %]
 
        &lt;img src=&quot;[% images %]/logo.gif&quot; align=right width=60 height=40&gt;
 
    [% END %]
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Here we've shown how pre-defined variables can be used as flags to
 
enable certain feature (e.g. <TT>&quot;graphics&quot;</TT>) and to specify common items
 
such as an email address and <FONT SIZE="-1">URL</FONT>'s for the home page, images directory
 
and so on.  This approach allows you to define these values once so
 
that they're consistent across all pages and can easily be changed to
 
new values.
 
<P>
 
 
 
When you run <I>ttree</I>, you should see output similar to the following
 
(assuming you have the verbose flag set).
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    ttree 2.9 (Template Toolkit version 2.20)
 
   
 
        Source: /home/abw/websrc/src
 
    Destination: /home/abw/public_html/test
 
  Include Path: [ /home/abw/websrc/lib ]
 
        Ignore: [ \b(CVS|RCS)\b, ^# ]
 
          Copy: [  ]
 
        Accept: [ * ]
 
       
 
    + newpage.html
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The <TT>&quot;+&quot;</TT> in front of the <TT>&quot;newpage.html&quot;</TT> filename shows that the file was
 
processed, with the output being written to the destination directory. If you
 
run the same command again, you'll see the following line displayed instead
 
showing a <TT>&quot;-&quot;</TT> and giving a reason why the file wasn't processed.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    - newpage.html                    (not modified)
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
It has detected a <TT>&quot;newpage.html&quot;</TT> in the destination directory which is
 
more recent than that in the source directory and so hasn't bothered
 
to waste time re-processing it.  To force all files to be processed,
 
use the <TT>&quot;-a&quot;</TT> option.  You can also specify one or more filenames as
 
command line arguments to <TT>&quot;ttree&quot;</TT>:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    tpage newpage.html
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
This is what the destination page looks like.
 
<P>
 
 
 
<TT>$dest</TT>/newpage.html:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    &lt;html&gt;
 
      &lt;head&gt;
 
        &lt;title&gt;Another Template Toolkit Test Page&lt;/title&gt;
 
      &lt;/head&gt;
 
      &lt;body&gt;
 
       
 
        &lt;a href=&quot;~/abw/index.html&quot;&gt;Home&lt;/a&gt;
 
        &lt;a href=&quot;mailto:<A HREF="mailto:abw@wardley.org">abw@wardley.org</A>&quot;&gt;Email me&lt;/a&gt;
 
        &lt;img src=&quot;~/abw/images/logo.gif&quot; align=right width=60 height=40&gt;
 
       
 
        &lt;div class=&quot;copyright&quot;&gt;
 
          &amp;copy; Copyright 2007 Arthur Dent
 
        &lt;/div&gt;
 
      &lt;/body&gt;
 
    &lt;/html&gt;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
You can add as many documents as you like to the <TT>&quot;src&quot;</TT> directory and
 
<TT>&quot;ttree&quot;</TT> will apply the same process to them all.  In this way, it is
 
possible to build an entire tree of static content for a web site with
 
a single command.  The added benefit is that you can be assured of
 
consistency in links, header style, or whatever else you choose to
 
implement in terms of common templates elements or variables.
 
<A NAME="lbAH">&nbsp;</A>
 
<H3>Dynamic Content Generation Via CGI Script</H3>
 
 
 
<A NAME="ixAAH"></A>
 
The Template module provides a simple front-end to the Template Toolkit for
 
use in <FONT SIZE="-1">CGI</FONT> scripts and Apache/mod_perl handlers. Simply <TT>&quot;use&quot;</TT> the Template
 
module, create an object instance with the <I>new()</I> method and then call the
 
<I>process()</I> method on the object, passing the name of the template file as a
 
parameter. The second parameter passed is a reference to a hash array of
 
variables that we want made available to the template:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    #!/usr/bin/perl
 
    use strict;
 
    use warnings;
 
    use Template;
 
   
 
    my $file = 'src/greeting.html';
 
    my $vars = {
 
      message  =&gt; &quot;Hello World\n&quot;
 
    };
 
   
 
    my $template = Template-&gt;new();
 
   
 
    $template-&gt;process($file, $vars)
 
        || die &quot;Template process failed: &quot;, $template-&gt;error(), &quot;\n&quot;;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
So that our scripts will work with the same template files as our earlier
 
examples, we'll can add some configuration options to the constructor to
 
tell it about our environment:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    my $template-&gt;new({
 
        # where to find template files
 
        INCLUDE_PATH =&gt; ['/home/abw/websrc/src', '/home/abw/websrc/lib'],
 
        # pre-process lib/config to define any extra values
 
        PRE_PROCESS  =&gt; 'config',
 
    });
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Note that here we specify the <TT>&quot;config&quot;</TT> file as a <TT>&quot;PRE_PROCESS&quot;</TT> option.
 
This means that the templates we process can use the same global
 
variables defined earlier for our static pages.  We don't have to
 
replicate their definitions in this script.  However, we can supply
 
additional data and functionality specific to this script via the hash
 
of variables that we pass to the <TT>&quot;process()&quot;</TT> method.
 
<P>
 
 
 
These entries in this hash may contain simple text or other values,
 
references to lists, others hashes, sub-routines or objects.  The Template
 
Toolkit will automatically apply the correct procedure to access these
 
different types when you use the variables in a template.
 
<P>
 
 
 
Here's a more detailed example to look over.  Amongst the different
 
template variables we define in <TT>$vars</TT>, we create a reference to a
 
<FONT SIZE="-1">CGI</FONT> object and a <TT>&quot;get_user_projects()&quot;</TT> sub-routine.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    #!/usr/bin/perl
 
    use strict;
 
    use warnings;
 
    use Template;
 
    use CGI;
 
   
 
    $| = 1;
 
    print &quot;Content-type: text/html\n\n&quot;;
 
   
 
    my $file = 'userinfo.html';
 
    my $vars = {
 
        'version'  =&gt; 3.14,
 
        'days'    =&gt; [ qw( mon tue wed thu fri sat sun ) ],
 
        'worklist' =&gt; \&amp;get_user_projects,
 
        'cgi'      =&gt; CGI-&gt;new(),
 
        'me'      =&gt; {
 
            'id'    =&gt; 'abw',
 
            'name'  =&gt; 'Andy Wardley',
 
        },
 
    };
 
   
 
    sub get_user_projects {
 
        my $user = shift;
 
        my @projects = ...  # do something to retrieve data
 
        return \@projects;
 
    }
 
   
 
    my $template = Template-&gt;new({
 
        INCLUDE_PATH =&gt; '/home/abw/websrc/src:/home/abw/websrc/lib',
 
        PRE_PROCESS  =&gt; 'config',
 
    });
 
   
 
    $template-&gt;process($file, $vars)
 
        || die $template-&gt;error();
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Here's a sample template file that we might create to build the output
 
for this script.
 
<P>
 
 
 
<TT>$src</TT>/userinfo.html:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% INCLUDE header
 
      title = 'Template Toolkit CGI Test'
 
    %]
 
   
 
    &lt;a href=&quot;mailto:[% email %]&quot;&gt;Email [% me.name %]&lt;/a&gt;
 
   
 
    &lt;p&gt;This is version [% version %]&lt;/p&gt;
 
   
 
    &lt;h3&gt;Projects&lt;/h3&gt;
 
    &lt;ul&gt;
 
    [% FOREACH project IN worklist(me.id) %]
 
      &lt;li&gt; &lt;a href=&quot;[% project.url %]&quot;&gt;[% project.name %]&lt;/a&gt;
 
    [% END %]
 
    &lt;/ul&gt;
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
This example shows how we've separated the Perl implementation (code) from the
 
presentation (<FONT SIZE="-1">HTML</FONT>). This not only makes them easier to maintain in isolation,
 
but also allows the re-use of existing template elements such as headers and
 
footers, etc. By using template to create the output of your <FONT SIZE="-1">CGI</FONT> scripts, you
 
can give them the same consistency as your static pages built via
 
ttree or other means.
 
<P>
 
 
 
Furthermore, we can modify our script so that it processes any one of a
 
number of different templates based on some condition.  A <FONT SIZE="-1">CGI</FONT> script to
 
maintain a user database, for example, might process one template to
 
provide an empty form for new users, the same form with some default
 
values set for updating an existing user record, a third template for
 
listing all users in the system, and so on.  You can use any Perl
 
functionality you care to write to implement the logic of your
 
application and then choose one or other template to generate the
 
desired output for the application state.
 
<A NAME="lbAI">&nbsp;</A>
 
<H3>Dynamic Content Generation Via Apache/Mod_Perl Handler</H3>
 
 
 
<A NAME="ixAAI"></A>
 
<B></B><FONT SIZE="-1"><B>NOTE:</B></FONT><B></B> the Apache::Template module is available from <FONT SIZE="-1">CPAN</FONT> and provides a
 
simple and easy to use Apache/mod_perl interface to the Template Toolkit.
 
Although basic, it implements most, if not all of what is described below, and
 
it avoids the need to write your own handler. However, in many cases, you'll
 
want to write your own handler to customise processing for your own need, and
 
this section will show you how to get started.
 
<P>
 
 
 
The Template module can be used from an Apache/mod_perl handler. Here's an
 
example of a typical Apache <I>httpd.conf</I> file:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    PerlModule CGI;
 
    PerlModule Template
 
    PerlModule MyOrg::Apache::User
 
   
 
    PerlSetVar websrc_root  /home/abw/websrc
 
   
 
    &lt;Location /user/bin&gt;
 
        SetHandler    perl-script
 
        PerlHandler    MyOrg::Apache::User
 
    &lt;/Location&gt;
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
This defines a location called <TT>&quot;/user/bin&quot;</TT> to which all requests will
 
be forwarded to the <TT>&quot;handler()&quot;</TT> method of the <TT>&quot;MyOrg::Apache::User&quot;</TT>
 
module.  That module might look something like this:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    package MyOrg::Apache::User;
 
   
 
    use strict;
 
    use vars qw( $VERSION );
 
    use Apache::Constants qw( :common );
 
    use Template qw( :template );
 
    use CGI;
 
   
 
    $VERSION = 1.59;
 
   
 
    sub handler {
 
        my $r = shift;
 
       
 
        my $websrc = $r-&gt;dir_config('websrc_root')
 
            or return fail($r, SERVER_ERROR,
 
                          &quot;'websrc_root' not specified&quot;);
 
                         
 
        my $template = Template-&gt;new({
 
            INCLUDE_PATH  =&gt; &quot;$websrc/src/user:$websrc/lib&quot;,
 
            PRE_PROCESS  =&gt; 'config',
 
            OUTPUT        =&gt; $r,    # direct output to Apache request
 
        });
 
       
 
        my $params = {
 
            uri    =&gt; $r-&gt;uri,
 
            cgi    =&gt; CGI-&gt;new,
 
        };
 
       
 
        # use the path_info to determine which template file to process
 
        my $file = $r-&gt;path_info;
 
        $file =~ s[^/][];
 
       
 
        $r-&gt;content_type('text/html');
 
        $r-&gt;send_http_header;
 
           
 
        $template-&gt;process($file, $params)
 
            || return fail($r, SERVER_ERROR, $template-&gt;error());
 
       
 
        return OK;
 
    }
 
   
 
    sub fail {
 
        my ($r, $status, $message) = @_;
 
        $r-&gt;log_reason($message, $r-&gt;filename);
 
        return $status;
 
    }
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The handler accepts the request and uses it to determine the <TT>&quot;websrc_root&quot;</TT>
 
value from the config file.  This is then used to define an <TT>&quot;INCLUDE_PATH&quot;</TT>
 
for a new Template object.  The <FONT SIZE="-1">URI</FONT> is extracted from the request and a
 
<FONT SIZE="-1">CGI</FONT> object is created.  These are both defined as template variables.
 
<P>
 
 
 
The name of the template file itself is taken from the <TT>&quot;PATH_INFO&quot;</TT> element
 
of the request.  In this case, it would comprise the part of the <FONT SIZE="-1">URL</FONT>
 
coming after <TT>&quot;/user/bin&quot;</TT>,  e.g for <TT>&quot;/user/bin/edit&quot;</TT>, the template file
 
would be <TT>&quot;edit&quot;</TT> located in <TT>&quot;$websrc/src/user&quot;</TT>.  The headers are sent
 
and the template file is processed.  All output is sent directly to the
 
<TT>&quot;print()&quot;</TT> method of the Apache request object.
 
<A NAME="lbAJ">&nbsp;</A>
 
<H3>Using Plugins to Extend Functionality</H3>
 
 
 
<A NAME="ixAAJ"></A>
 
As we've already shown, it is possible to bind Perl data and functions
 
to template variables when creating dynamic content via a <FONT SIZE="-1">CGI</FONT> script
 
or Apache/mod_perl process.  The Template Toolkit also supports a
 
plugin interface which allows you define such additional data and/or
 
functionality in a separate module and then load and use it as
 
required with the <TT>&quot;USE&quot;</TT> directive.
 
<P>
 
 
 
The main benefit to this approach is that you can load the extension into
 
any template document, even those that are processed ``statically'' by
 
<TT>&quot;tpage&quot;</TT> or <TT>&quot;ttree&quot;</TT>.  You <I>don't</I> need to write a Perl wrapper to
 
explicitly load the module and make it available via the stash.
 
<P>
 
 
 
Let's demonstrate this principle using the <TT>&quot;DBI&quot;</TT> plugin written by Simon
 
Matthews (available from <FONT SIZE="-1">CPAN</FONT>). You can create this template in your <TT>&quot;src&quot;</TT>
 
directory and process it using <TT>&quot;ttree&quot;</TT> to see the results. Of course, this
 
example relies on the existence of the appropriate <FONT SIZE="-1">SQL</FONT> database but you should
 
be able to adapt it to your own resources, or at least use it as a
 
demonstrative example of what's possible.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% INCLUDE header
 
        title = 'User Info'
 
    %]
 
   
 
    [% USE DBI('dbi:mSQL:mydbname') %]
 
   
 
    &lt;table border=0 width=&quot;100%&quot;&gt;
 
      &lt;tr&gt;
 
        &lt;th&gt;User ID&lt;/th&gt;
 
        &lt;th&gt;Name&lt;/th&gt; 
 
        &lt;th&gt;Email&lt;/th&gt;
 
      &lt;/tr&gt;
 
    [% FOREACH user IN DBI.query('SELECT * FROM user ORDER BY id') %]
 
      &lt;tr&gt;
 
        &lt;td&gt;[% user.id %]&lt;/td&gt;
 
        &lt;td&gt;[% user.name %]&lt;/td&gt;
 
        &lt;td&gt;[% user.email %]&lt;/td&gt;
 
      &lt;/tr&gt;
 
    [% END %]
 
    &lt;/table&gt;
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
A plugin is simply a Perl module in a known location and conforming to
 
a known standard such that the Template Toolkit can find and load it
 
automatically.  You can create your own plugin by inheriting from the
 
Template::Plugin module.
 
<P>
 
 
 
Here's an example which defines some data items (<TT>&quot;foo&quot;</TT> and <TT>&quot;people&quot;</TT>)
 
and also an object method (<TT>&quot;bar&quot;</TT>).  We'll call the plugin <TT>&quot;FooBar&quot;</TT> for
 
want of a better name and create it in the <TT>&quot;MyOrg::Template::Plugin::FooBar&quot;</TT>
 
package.  We've added a <TT>&quot;MyOrg&quot;</TT> to the regular <TT>&quot;Template::Plugin::*&quot;</TT> package
 
to avoid any conflict with existing plugins.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    package MyOrg::Template::Plugin::FooBar;
 
    use base 'Template::Plugin'
 
    our $VERSION = 1.23;
 
   
 
    sub new {
 
        my ($class, $context, @params) = @_;
 
       
 
        bless {
 
            _CONTEXT =&gt; $context,
 
            foo      =&gt; 25,
 
            people  =&gt; [ 'tom', 'dick', 'harry' ],
 
        }, $class;
 
    }
 
   
 
    sub bar {
 
        my ($self, @params) = @_;
 
        # ...do something...   
 
        return $some_value;
 
    }
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The plugin constructor <TT>&quot;new()&quot;</TT> receives the class name as the first
 
parameter, as is usual in Perl, followed by a reference to something called a
 
Template::Context object. You don't need to worry too much about this at
 
the moment, other than to know that it's the main processing object for the
 
Template Toolkit. It provides access to the functionality of the processor and
 
some plugins may need to communicate with it. We don't at this stage, but
 
we'll save the reference anyway in the <TT>&quot;_CONTEXT&quot;</TT> member. The leading
 
underscore is a convention which indicates that this item is private and the
 
Template Toolkit won't attempt to access this member. The other members
 
defined, <TT>&quot;foo&quot;</TT> and <TT>&quot;people&quot;</TT> are regular data items which will be made
 
available to templates using this plugin. Following the context reference are
 
passed any additional parameters specified with the <FONT SIZE="-1">USE</FONT> directive, such as the
 
data source parameter, <TT>&quot;dbi:mSQL:mydbname&quot;</TT>, that we used in the earlier <FONT SIZE="-1">DBI</FONT>
 
example.
 
<P>
 
 
 
If you don't or can't install it to the regular place for your Perl
 
modules (perhaps because you don't have the required privileges) then
 
you can set the <FONT SIZE="-1">PERL5LIB</FONT> environment variable to specify another location.
 
If you're using <TT>&quot;ttree&quot;</TT> then you can add the following line to your
 
configuration file instead.
 
<P>
 
 
 
<TT>$HOME</TT>/.ttreerc:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    perl5lib = /path/to/modules
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
One further configuration item must be added to inform the toolkit of
 
the new package name we have adopted for our plugins:
 
<P>
 
 
 
<TT>$HOME</TT>/.ttreerc:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    plugin_base = 'MyOrg::Template::Plugin'
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
If you're writing Perl code to control the Template modules directly,
 
then this value can be passed as a configuration parameter when you
 
create the module.
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    use Template;
 
   
 
    my $template = Template-&gt;new({
 
        PLUGIN_BASE =&gt; 'MyOrg::Template::Plugin'
 
    });
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
Now we can create a template which uses this plugin:
 
<P>
 
 
 
 
 
 
 
<PRE>
 
    [% INCLUDE header
 
      title = 'FooBar Plugin Test'
 
    %]
 
   
 
    [% USE FooBar %]
 
   
 
    Some values available from this plugin:
 
      [% FooBar.foo %] [% FooBar.bar %]
 
     
 
    The users defined in the 'people' list:
 
    [% FOREACH uid = FooBar.people %]
 
      * [% uid %]
 
    [% END %]
 
   
 
    [% INCLUDE footer %]
 
 
 
</PRE>
 
 
 
 
 
<P>
 
 
 
The <TT>&quot;foo&quot;</TT>, <TT>&quot;bar&quot;</TT>, and <TT>&quot;people&quot;</TT> items of the FooBar plugin are
 
automatically resolved to the appropriate data items or method calls
 
on the underlying object.
 
<P>
 
 
 
Using this approach, it is possible to create application
 
functionality in a single module which can then be loaded and used on
 
demand in any template.  The simple interface between template
 
directives and plugin objects allows complex, dynamic content to be
 
built from a few simple template documents without knowing anything
 
about the underlying implementation.
 
<A NAME="lbAK">&nbsp;</A>
 
<H3>AUTHOR</H3>
 
 
 
<A NAME="ixAAK"></A>
 
Andy Wardley &lt;<A HREF="mailto:abw@wardley.org">abw@wardley.org</A>&gt; &lt;<A HREF="http://wardley.org/">http://wardley.org/</A>&gt;
 
<A NAME="lbAL">&nbsp;</A>
 
<H3>COPYRIGHT</H3>
 
 
 
<A NAME="ixAAL"></A>
 
Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
 
<P>
 
 
 
This module is free software; you can redistribute it and/or
 
modify it under the same terms as Perl itself.
 
<P>
 
 
 
<HR>
 
<A NAME="index">&nbsp;</A><H2>Index</H2>
 
<DL>
 
<DT><A HREF="#lbAB">NAME</A><DD>
 
<DT><A HREF="#lbAC">Overview</A><DD>
 
<DT><A HREF="#lbAD">Introduction</A><DD>
 
<DT><A HREF="#lbAE">Generating Static Web Content</A><DD>
 
<DL>
 
<DT><A HREF="#lbAF">Using tpage</A><DD>
 
<DT><A HREF="#lbAG">Using ttree</A><DD>
 
</DL>
 
<DT><A HREF="#lbAH">Dynamic Content Generation Via CGI Script</A><DD>
 
<DT><A HREF="#lbAI">Dynamic Content Generation Via Apache/Mod_Perl Handler</A><DD>
 
<DT><A HREF="#lbAJ">Using Plugins to Extend Functionality</A><DD>
 
<DT><A HREF="#lbAK">AUTHOR</A><DD>
 
<DT><A HREF="#lbAL">COPYRIGHT</A><DD>
 
</DL>
 

Latest revision as of 15:40, 15 March 2014

CssWork - parent of these pages
ThemesAnatomy - parent of this page

Index of Template pages

Official docs for templates from docs/HOWTO-Templates.pod

HOWTO-Templates - How to write Slash templates

QUESTIONS

What is a template?

A template is a bit of text that is parsed by Perl, using the Template Toolkit. Template Toolkit has support for variables, control structures, and more. It is more easily understood and edited by non-programmers than is Perl, and it is much safer than executing raw Perl code.

Templates are compiled into Perl functions and the resulting compiled code is cached. Templates are fast and convenient and easy.

For more information on how templates are written, see the man pages for Slash::Display and Template, and the Template Toolkit web page at E<lt>URL:http://www.template-toolkit.org/E<gt>.

How do I get my template into a running site?

Use the Template Editor via the admin menu on the site, or use template-tool on the command line. You can find out information on it by calling it with the "-h" option.


How do I get my template installed with a plugin/theme?

For a plugin it has to be added to the PLUGIN file (see F<HOWTO-Plugins>). For a theme it just needs to be in the templates directory for the theme (see F<HOWTO-Themes>).


What language encoding are the templates using?

There is a language field for templates, which is, by default, "en_US". However, it is not currently used by the code. We have not entirely decided how to handle languages yet.

Currently, the language is based on the same method used to determine locales on Unix: two-letter, lowercase, ISO 639 codes for language; two-letter, uppercase, ISO 3166 codes for country; joined with an underscore. e.g., en_US, en_CA, de_DE, zh_CN, ja_JP.


How do I generate a blank template?

Use template-tool:

	template-tool -g filename

Can I set my own Template options?

You can change some of the configuration options of Template, (PRE_CHOMP, POST_CHOMP, and CACHE_SIZE) via the vars table. Most options cannot be changed, however, except by editing the Slash::Display module directly.


What can I do about whitespace between template tags?

The TRIM option (which removes whitespace before and after templates) is on by default. Many things in Slash will fail if TRIM is not true, because it is expected that whitespace will be removed before and after a returned template.

PRE_CHOMP and POST_CHOMP (which remove whitespace before and after individual tags) are off by default, but may be turned on via the template_pre_chomp and template_post_chomp entries in the vars table. In an upcoming version of Template, there will be a third option, other than just "on" and "off": "collapse". This will collapse whitespace between tags down to a single space, and will most likely be ideal for use in Slash, since runs of whitespace in HTML is the same as a single space, in most situations.

You can enable and disable chomping of whitespace for individual tags with "+" and "-". To enable chomping, write a tag like this:

	[% num %] comment
		[%- IF num != 1 ; 's' ; END %]

That will push the "s" character up against the end of "comment", if it is printed.

If CHOMP is enabled, you can disable it in the same way, with "+" instead of "-". See L<Template::Parser>.


I have a really cool template for a theme/plugin, and I would like to see it added to the Slash distribution. Will you distribute mine?

Maybe. We don't have any rules concerning this at the moment, so it will be on a case by case basis. At some point in the future we will come up with a much better answer. If the theme or plugin is one not included with the Slash distribution, you should contact the theme's or plugin's creator directly.

SEE ALSO

Slash::Display(3).

Template library Docs

Slash uses the Template Library for its templates, so if you want to be able to add or change html, some knowledge of how it works is useful.

Its man pages are in /usr/local/share/man/man3 - the introduction is reproduced below as an overview.

man Template\:\:Tutorial\:\:Web will get you this

Some of these including the template tutorial listed top of this page, with wiki pages.