local-lib5/man/man3/Template::Manual::Intro.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::Manual::Intro 3"
 132 .TH Template::Manual::Intro 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Manual::Intro \- Introduction to the Template Toolkit
 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 It is most often used for generating dynamic web content, although it can
 140 be used equally well for processing any kind of text documents.
 141 .PP
 142 At the simplest level it provides an easy way to process template
 143 files, filling in embedded variable references with their equivalent
 144 values.  Here's an example of a template.
 145 .PP
 146 .Vb 1
 147 \&    Dear [% name %],
 148 .Ve
 149 .PP
 150 .Vb 2
 151 \&    It has come to our attention that your account is in
 152 \&    arrears to the sum of [% debt %].
 153 .Ve
 154 .PP
 155 .Vb 2
 156 \&    Please settle your account before [% deadline %] or we
 157 \&    will be forced to revoke your Licence to Thrill.
 158 .Ve
 159 .PP
 160 .Vb 1
 161 \&    The Management.
 162 .Ve
 163 .PP
 164 By default, template directives are embedded within the character
 165 sequences \f(CW\*(C`[%\*(C'\fR ... \f(CW\*(C`%]\*(C'\fR but you can change these and various other
 166 options to configure how the Template Toolkit looks, feels and works.
 167 You can set the \f(CW\*(C`INTERPOLATE\*(C'\fR option, for example, if you prefer to
 168 embed your variables in Perl style:
 169 .PP
 170 .Vb 1
 171 \&    Dear $name,
 172 .Ve
 173 .PP
 174 .Vb 2
 175 \&    It has come to our attention that your account is in
 176 \&    arrears to the sum of $debt.
 177 .Ve
 178 .PP
 179 .Vb 1
 180 \&    ...etc...
 181 .Ve
 182 .SH "The Template Perl Module"
 183 .IX Header "The Template Perl Module"
 184 The Template Perl module is the front end to the Template Toolkit for Perl
 185 programmers, providing access to the full range of functionality through a
 186 single module with a simple interface. It loads the other modules as required
 187 and instantiates a default set of objects to handle subsequent template
 188 processing requests. Configuration parameters may be passed to the Template
 189 constructor method, \fInew()\fR, which are then used to
 190 configure the generate object.
 191 .PP
 192 .Vb 1
 193 \&    use Template;
 194 .Ve
 195 .PP
 196 .Vb 4
 197 \&    my $tt = Template\->new({
 198 \&        INCLUDE_PATH => '/usr/local/templates',
 199 \&        INTERPOLATE  => 1,
 200 \&    }) || die "$Template::ERROR\en";
 201 .Ve
 202 .PP
 203 The Template object implements a \fIprocess()\fR method for
 204 processing template files or text. The name of the input template (or various
 205 other sources) is passed as the first argument, followed by a reference to a
 206 hash array of variable definitions for substitution in the template.
 207 .PP
 208 .Vb 5
 209 \&    my $vars = {
 210 \&        name     => 'Count Edward van Halen',
 211 \&        debt     => '3 riffs and a solo',
 212 \&        deadline => 'the next chorus',
 213 \&    };
 214 .Ve
 215 .PP
 216 .Vb 2
 217 \&    $tt\->process('letters/overdrawn', $vars)
 218 \&        || die $tt\->error(), "\en";
 219 .Ve
 220 .PP
 221 The \fIprocess()\fR method returns a true value (\f(CW1\fR) on success
 222 and prints the template output to \f(CW\*(C`STDOUT\*(C'\fR, by default. On error, the
 223 \&\fIprocess()\fR method returns a false value (\f(CW\*(C`undef\*(C'\fR).
 224 The \fIerror()\fR method can then be called to retrieve
 225 details of the error.
 226 .SH "Component Based Content Construction"
 227 .IX Header "Component Based Content Construction"
 228 A number of special directives are provided, such as \f(CW\*(C`INSERT\*(C'\fR, \f(CW\*(C`INCLUDE\*(C'\fR and
 229 \&\f(CW\*(C`PROCESS\*(C'\fR, which allow content to be built up from smaller template
 230 components. This permits a modular approach to building a web site or other
 231 content repository, promoting reusability, cross-site consistency, ease of
 232 construction and subsequent maintenance. Common elements such as headers,
 233 footers, menu bars, tables, and so on, can be created as separate template
 234 files which can then be processed into other documents as required. All
 235 defined variables are inherited by these templates along with any additional
 236 \&\*(L"local\*(R" values specified.
 237 .PP
 238 .Vb 3
 239 \&    [% PROCESS header
 240 \&         title = "The Cat Sat on the Mat"
 241 \&    %]
 242 .Ve
 243 .PP
 244 .Vb 1
 245 \&    [% PROCESS menu %]
 246 .Ve
 247 .PP
 248 .Vb 2
 249 \&    The location of the missing feline has now been established.
 250 \&    Thank you for your assistance.
 251 .Ve
 252 .PP
 253 .Vb 1
 254 \&    [% INSERT legal/disclaimer %]
 255 .Ve
 256 .PP
 257 .Vb 1
 258 \&    [% PROCESS footer %]
 259 .Ve
 260 .PP
 261 You can also define a template as a \s-1BLOCK\s0 within the same file and
 262 \&\s-1PROCESS\s0 it just like any other template file.  This can be invaluable
 263 for building up repetitive elements such as tables, menus, etc.
 264 .PP
 265 .Vb 3
 266 \&    [% BLOCK tabrow %]
 267 \&       <tr><td>[% name %]</td><td>[% email %]</td></tr>
 268 \&    [% END %]
 269 .Ve
 270 .PP
 271 .Vb 5
 272 \&    <table>
 273 \&    [% PROCESS tabrow name="tom"   email="tom@here.org"    %]
 274 \&    [% PROCESS tabrow name="dick"  email="disk@there.org"  %]
 275 \&    [% PROCESS tabrow name="larry" email="larry@where.org" %]
 276 \&    </table>
 277 .Ve
 278 .SH "Data and Code Binding"
 279 .IX Header "Data and Code Binding"
 280 One of the key features that sets the Template Toolkit apart from
 281 other template processors is the ability to bind template variables to
 282 any kind of Perl data: scalars, lists, hash arrays, sub-routines and
 283 objects.
 284 .PP
 285 .Vb 10
 286 \&    my $vars = {
 287 \&        root   => 'http://here.com/there',
 288 \&        menu   => [ 'modules', 'authors', 'scripts' ],
 289 \&        client => {
 290 \&            name => 'Doctor Joseph von Satriani',
 291 \&            id   => 'JVSAT',
 292 \&        },
 293 \&        checkout => sub { my $total = shift; ...; return $something },
 294 \&        shopcart => My::Cool::Shopping::Cart\->new(),
 295 \&    };
 296 .Ve
 297 .PP
 298 The Template Toolkit will automatically Do The Right Thing to access the data
 299 in an appropriate manner to return some value which can then be output. The
 300 dot operator '\f(CW\*(C`.\*(C'\fR' is used to access into lists and hashes or to call object
 301 methods. The \f(CW\*(C`FOREACH\*(C'\fR directive is provided for iterating through lists, and
 302 various logical tests are available using directives such as \f(CW\*(C`IF\*(C'\fR, \f(CW\*(C`UNLESS\*(C'\fR,
 303 \&\f(CW\*(C`ELSIF\*(C'\fR, \f(CW\*(C`ELSE\*(C'\fR, \f(CW\*(C`SWITCH\*(C'\fR, \f(CW\*(C`CASE\*(C'\fR, etc.
 304 .PP
 305 .Vb 3
 306 \&    [% FOREACH section = menu %]
 307 \&       <a href="[% root %]/[% section %]/index.html">[% section %]</a>
 308 \&    [% END %]
 309 .Ve
 310 .PP
 311 .Vb 1
 312 \&    <b>Client</a>: [% client.name %] (id: [% client.id %])
 313 .Ve
 314 .PP
 315 .Vb 7
 316 \&    [% IF shopcart.nitems %]
 317 \&       Your shopping cart contains the following items:
 318 \&       <ul>
 319 \&       [% FOREACH item = shopcart.contents %]
 320 \&         <li>[% item.name %] : [% item.qty %] @ [% item.price %]
 321 \&       [% END %]
 322 \&       </ul>
 323 .Ve
 324 .PP
 325 .Vb 1
 326 \&       [% checkout(shopcart.total) %]
 327 .Ve
 328 .PP
 329 .Vb 3
 330 \&    [% ELSE %]
 331 \&       No items currently in shopping cart.
 332 \&    [% END %]
 333 .Ve
 334 .SH "Advanced Features: Filters, Macros, Exceptions, Plugins"
 335 .IX Header "Advanced Features: Filters, Macros, Exceptions, Plugins"
 336 The Template Toolkit also provides a number of additional directives
 337 for advanced processing and programmatical functionality.  It supports
 338 output filters (\s-1FILTER\s0), allows custom macros to be defined (\s-1MACRO\s0),
 339 has a fully-featured exception handling system (\s-1TRY\s0, \s-1THROW\s0, \s-1CATCH\s0,
 340 \&\s-1FINAL\s0) and supports a plugin architecture (\s-1USE\s0) which allows special
 341 plugin modules and even regular Perl modules to be loaded and used
 342 with the minimum of fuss.  The Template Toolkit is \*(L"just\*(R" a template
 343 processor but you can trivially extend it to incorporate the
 344 functionality of any Perl module you can get your hands on.  Thus, it
 345 is also a scalable and extensible template framework, ideally suited
 346 for managing the presentation layer for application servers, content
 347 management systems and other web applications.
 348 .SH "Separating Presentation and Application Logic"
 349 .IX Header "Separating Presentation and Application Logic"
 350 Rather than embedding Perl code or some other scripting language
 351 directly into template documents, it encourages you to keep functional
 352 components (i.e. Perl code) separate from presentation components
 353 (e.g. \s-1HTML\s0 templates).  The template variables provide the interface
 354 between the two layers, allowing data to be generated in code and then
 355 passed to a template component for displaying (pipeline model) or for
 356 sub-routine or object references to be bound to variables which can
 357 then be called from the template as and when required (callback
 358 model).
 359 .PP
 360 The directives that the Template Toolkit provide implement their own
 361 mini programming language, but they're not really designed for
 362 serious, general purpose programming.  Perl is a far more appropriate
 363 language for that.  If you embed application logic (e.g. Perl or other
 364 scripting language fragments) in \s-1HTML\s0 templates then you risk losing
 365 the clear separation of concerns between functionality and
 366 presentation.  It becomes harder to maintain the two elements in
 367 isolation and more difficult, if not impossible, to reuse code or
 368 presentation elements by themselves.  It is far better to write your
 369 application code in separate Perl modules, libraries or scripts and
 370 then use templates to control how the resulting data is presented as
 371 output.  Thus you should think of the Template Toolkit language as a
 372 set of layout directives for displaying data, not calculating it.
 373 .PP
 374 Having said that, the Template Toolkit doesn't force you into one
 375 approach or the other.  It attempts to be pragmatic rather than
 376 dogmatic in allowing you to do whatever best gets the job done.
 377 Thus, if you enable the \s-1EVAL_PERL\s0 option then you can happily embed
 378 real Perl code in your templates within \s-1PERL\s0 ... \s-1END\s0 directives.
 379 .SH "Performance"
 380 .IX Header "Performance"
 381 The Template Toolkit uses a fast YACC-like parser which compiles
 382 templates into Perl code for maximum runtime efficiency.  It also has
 383 an advanced caching mechanism which manages in-memory and on-disk
 384 (i.e. persistent) versions of compiled templates.  The modules that
 385 comprise the toolkit are highly configurable and the architecture
 386 around which they're built is designed to be extensible.  The Template
 387 Toolkit provides a powerful framework around which content creation
 388 and delivery systems can be built while also providing a simple
 389 interface through the Template front-end module for general use.