local-lib5/man/man3/Template::Toolkit.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Toolkit 3"
 132 .TH Template::Toolkit 3 "2009-07-20" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Toolkit \- Template Processing System
 135 .SH "Introduction"
 136 .IX Header "Introduction"
 137 The Template Toolkit is a collection of Perl modules which implement a
 138 fast, flexible, powerful and extensible template processing system.
 139 .PP
 140 It is \*(L"input\-agnostic\*(R" and can be used equally well for processing any
 141 kind of text documents: \s-1HTML\s0, \s-1XML\s0, \s-1CSS\s0, Javascript, Perl code, plain text,
 142 and so on.  However, it is most often used for generating static and
 143 dynamic web content, so that's what we'll focus on here.
 144 .PP
 145 Although the Template Toolkit is written in Perl, you don't need to be a Perl
 146 programmer to use it. It was designed to allow non-programmers to easily
 147 create and maintain template-based web sites without having to mess around
 148 writing Perl code or going crazy with cut\-n\-paste.
 149 .PP
 150 However, the Template Toolkit is also designed to be extremely flexible and
 151 extensible. If you are a Perl programmer, or know someone who is, then you can
 152 easily hook the Template Toolkit into your existing code, data, databases and
 153 web applications. Furthermore, you can easily extend the Template Toolkit
 154 through the use of its plugin mechanism and other developer APIs.
 155 .PP
 156 Whatever context you use it in, the primary purpose of the Template Toolkit is
 157 to allow you to create a clear separation between the presentation elements of
 158 your web site and everything else.
 159 .PP
 160 If you're generating static web pages, then you can use it to separate the
 161 commonly repeated user interface elements on each page (headers, menus,
 162 footers, etc.) from the core content. If you're generating dynamic web pages
 163 for the front end of a web application, then you'll also be using it to keep
 164 the back-end Perl code entirely separate from the front-end \s-1HTML\s0 templates.
 165 Either way, a \fIclear separation of concerns\fR is what allow you to
 166 concentrate on one thing at a time without the other things getting in your
 167 way.  And that's what the Template Toolkit is all about.
 168 .SH "Documentation"
 169 .IX Header "Documentation"
 170 The documentation for the Template Toolkit is organised into five sections.
 171 .PP
 172 The Template::Manual contains detailed information about using the Template
 173 Toolkit. It gives examples of its use and includes a full reference of the
 174 template language, configuration options, filters, plugins and other component
 175 parts.
 176 .PP
 177 The Template::Modules page lists the Perl modules that comprise the
 178 Template Toolkit. It gives a brief explanation of what each of them does, and
 179 provides a link to the complete documentation for each module for further
 180 information. If you're a Perl programmer looking to use the Template Toolkit
 181 from your Perl programs then this section is likely to be of interest.
 182 .PP
 183 Most, if not all of the information you need to call the Template Toolkit from
 184 Perl is in the documentation for the Template module. You only really need
 185 to start thinking about the other modules if you want to extend or modify the
 186 Template Toolkit in some way, or if you're interested in looking under the
 187 hood to see how it all works.
 188 .PP
 189 The documentation for each module is embedded as \s-1POD\s0 in each
 190 module, so you can always use \f(CW\*(C`perldoc\*(C'\fR from the command line to read a
 191 module's documentation.  e.g.
 192 .PP
 193 .Vb 3
 194 \&    $ perldoc Template
 195 \&    $ perldoc Template::Context
 196 \&      ...etc...
 197 .Ve
 198 .PP
 199 It's worth noting that all the other documentation, including the user manual
 200 is available as \s-1POD\s0.  e.g.
 201 .PP
 202 .Vb 3
 203 \&    $ perldoc Template::Manual
 204 \&    $ perldoc Template::Manual::Config
 205 \&      ...etc...
 206 .Ve
 207 .PP
 208 The Template::Tools section contains the documentation for
 209 Template::Tools::tpage and Template::Tools::ttree.
 210 These are two command line programs that are distributed with the
 211 Template Toolkit.  tpage is used to process
 212 a single template file, ttree for processing
 213 entire directories of template files.
 214 .PP
 215 The Template::Tutorial section contains two introductory tutorials on using
 216 the Template Toolkit. The first is Template::Tutorial::Web on generating
 217 web content. The second is Template::Tutorial::Datafile on using the
 218 Template Toolkit to generate other data formats including \s-1XML\s0.
 219 .PP
 220 The final section of the manual is Template::FAQ which contains answers
 221 to some of the Frequently Asked Questions about the Template Toolkit.
 222 .PP
 223 You can read the documentation in \s-1HTML\s0 format either online at the Template
 224 Toolkit web site, <http://template\-toolkit.org/>, or by downloading the
 225 \&\s-1HTML\s0 version of the documentation from
 226 <http://template\-toolkit.org/download/index.html#html_docs> and unpacking
 227 it on your local machine.
 228 .SH "Author"
 229 .IX Header "Author"
 230 The Template Toolkit was written by Andy Wardley (<http://wardley.org/>
 231 <mailto:abw@wardley.org>) with assistance and contributions from a great
 232 number of people.  Please see Template::Manual::Credits for a full list.
 233 .SH "Copyright"
 234 .IX Header "Copyright"
 235 Copyright (C) 1996\-2008 Andy Wardley.  All Rights Reserved.
 236 .PP
 237 This module is free software; you can redistribute it and/or
 238 modify it under the same terms as Perl itself.
 239 .SH "See Also"
 240 .IX Header "See Also"
 241 Template, Template::Manual, Template::Modules, Template::Tools,
 242 Template::Tutorial