local-lib5/man/man3/Template::FAQ.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::FAQ 3"
 132 .TH Template::FAQ 3 "2009-07-20" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::FAQ \- Frequently Asked Questions about the Template Toolkit
 135 .SH "Template Toolkit Language"
 136 .IX Header "Template Toolkit Language"
 137 .Sh "Why doesn't [% a = b \s-1IF\s0 c %] work as expected?"
 138 .IX Subsection "Why doesn't [% a = b IF c %] work as expected?"
 139 There's a limitation in the \s-1TT2\s0 parser which means that the following code
 140 doesn't work as you might expect:
 141 .PP
 142 .Vb 1
 143 \&    [% a = b IF c %]
 144 .Ve
 145 .PP
 146 The parser interprets it as an attempt to set \f(CW\*(C`a\*(C'\fR to the result of
 147 \&\f(CW\*(C`b IF c\*(C'\fR, like this:
 148 .PP
 149 .Vb 1
 150 \&    [% a = (b IF c) %]
 151 .Ve
 152 .PP
 153 If you want to set \f(CW\*(C`a = b\*(C'\fR only if \f(CW\*(C`c\*(C'\fR is true, then do this instead:
 154 .PP
 155 .Vb 1
 156 \&    [% SET a = b IF c %]
 157 .Ve
 158 .PP
 159 The explicit \f(CW\*(C`SET\*(C'\fR keyword gives the parser the clue it needs to do the
 160 right thing.
 161 .PP
 162 \&\s-1NOTE:\s0 this will be fixed in \s-1TT3\s0
 163 .Sh "If I'm using \s-1TT\s0 to write out a \s-1TT\s0 template, is there a good way to escape [% and %]?"
 164 .IX Subsection "If I'm using TT to write out a TT template, is there a good way to escape [% and %]?"
 165 You can do something like this:
 166 .PP
 167 .Vb 3
 168 \&    [% stag = "[\e%"
 169 \&       etag = "%\e]"
 170 \&    %]
 171 .Ve
 172 .PP
 173 and then:
 174 .PP
 175 .Vb 1
 176 \&    [% stag; 'hello'; etag %]
 177 .Ve
 178 .PP
 179 Or you can use the \f(CW\*(C`TAGS\*(C'\fR directive, like so:
 180 .PP
 181 .Vb 3
 182 \&    [% TAGS [\- \-] %]
 183 \&    [\- INCLUDE foo \-]   # is a directive
 184 \&    [% INCLUDE foo %]   # not a directive
 185 .Ve
 186 .Sh "How do I iterate over a hash?"
 187 .IX Subsection "How do I iterate over a hash?"
 188 This is covered in the Template::Manual::VMethods section of the
 189 manual. A list of all the keys that are in the hash can be obtained with the
 190 \&\f(CW\*(C`keys\*(C'\fR virtual method. You can then iterate over that list and by looking up
 191 each key in turn get the value.
 192 .PP
 193 .Vb 3
 194 \&    [% FOREACH key = product.keys %]
 195 \&       [% key %] => [% product.$key %]
 196 \&    [% END %]
 197 .Ve
 198 .SH "Plugins"
 199 .IX Header "Plugins"
 200 .Sh "How do I get the Table plugin to order data across rather than down?"
 201 .IX Subsection "How do I get the Table plugin to order data across rather than down?"
 202 Order the data into rows:
 203 .PP
 204 .Vb 3
 205 \&    Steve     Karen     Jeff
 206 \&    Brooklyn  Nantucket Fairfax
 207 \&    NY        MA        VA
 208 .Ve
 209 .PP
 210 .Vb 1
 211 \&    [% USE table(data, rows=3) %]
 212 .Ve
 213 .PP
 214 Then ask for each column
 215 .PP
 216 .Vb 1
 217 \&    [% FOREACH column = table.cols %]
 218 .Ve
 219 .PP
 220 And then print each item in the column going across the output rows
 221 .PP
 222 .Vb 3
 223 \&    [% FOREACH item = column %]
 224 \&        <td>[% item %]</td>
 225 \&    [% END %]
 226 .Ve
 227 .Sh "Accessing Cookies"
 228 .IX Subsection "Accessing Cookies"
 229 Jeff Boes <jboes@nexcerpt.com> asks:
 230 .PP
 231 .Vb 2
 232 \&    Does anyone have a quick\-n\-dirty approach to accessing
 233 \&    cookies from templates?
 234 .Ve
 235 .PP
 236 Jonas Liljegren answers:
 237 .PP
 238 .Vb 1
 239 \&    [% USE CGI %]
 240 .Ve
 241 .PP
 242 .Vb 1
 243 \&    <p>The value is [% CGI.cookie('cookie_name') | html %]
 244 .Ve
 245 .SH "Extending the Template Toolkit"
 246 .IX Header "Extending the Template Toolkit"
 247 .Sh "Can I serve templates from a database?"
 248 .IX Subsection "Can I serve templates from a database?"
 249 Short answer: yes, Chris Nandor has done this for Slash.  You need to
 250 subclass Template::Provider.  See the mailing list archives for further
 251 info.
 252 .Sh "Can I fetch templates via http?"
 253 .IX Subsection "Can I fetch templates via http?"
 254 To do the job properly, you should subclass Template::Provider to
 255 \&\f(CW\*(C`Template::Provider::HTTP\*(C'\fR and use a \f(CW\*(C`PREFIX_MAP\*(C'\fR option to bind the \f(CW\*(C`http\*(C'\fR
 256 template prefix to that particular provider (you may want to go digging around
 257 in the \fIChanges\fR file around version 2.01 for more info on \f(CW\*(C`PREFIX_MAP\*(C'\fR \- it
 258 may not be properly documented anywhere else...yet!). e.g.
 259 .PP
 260 .Vb 1
 261 \&    use Template::Provider::HTTP;
 262 .Ve
 263 .PP
 264 .Vb 10
 265 \&    my $file = Template::Provider( INCLUDE_PATH => [...] );
 266 \&    my $http = Template::Provider::HTTP\->new(...);
 267 \&    my $tt2  = Template\->new({
 268 \&        LOAD_TEMPLATES => [ $file, $http ],
 269 \&        PREFIX_MAP => {
 270 \&            file    => '0',     # file:foo.html
 271 \&            http    => '1',     # http:foo.html
 272 \&            default => '0',     # foo.html => file:foo.html
 273 \&        }
 274 \&    });
 275 .Ve
 276 .PP
 277 Now a template specified as:
 278 .PP
 279 .Vb 1
 280 \&    [% INCLUDE foo %]
 281 .Ve
 282 .PP
 283 will be served by the 'file' provider (the default).  Otherwise you
 284 can explicitly add a prefix:
 285 .PP
 286 .Vb 3
 287 \&    [% INCLUDE file:foo.html %]
 288 \&    [% INCLUDE http:foo.html %]
 289 \&    [% INCLUDE http://www.xyz.com/tt2/header.tt2 %]
 290 .Ve
 291 .PP
 292 This same principal can be used to create a \s-1DBI\s0 template provider.  e.g.
 293 .PP
 294 .Vb 1
 295 \&    [% INCLUDE dbi:foo.html %]
 296 .Ve
 297 .PP
 298 Alas, we don't yet have a \s-1DBI\s0 provider as part of the Template Toolkit. There
 299 has been some talk on the mailing list about efforts to develop \s-1DBI\s0 and/or
 300 \&\s-1HTTP\s0 providers but as yet no-one has stepped forward to take up the
 301 challenge...
 302 .PP
 303 In the mean time, Craig Barrat's post from the mailing list has some useful
 304 pointers on how to achieve this using existing modules.  See
 305 <http://tt2.org/pipermail/templates/2001\-May/000954.html>
 306 .SH "Miscellaneous"
 307 .IX Header "Miscellaneous"
 308 .Sh "How can I find out the name of the main template being processed?"
 309 .IX Subsection "How can I find out the name of the main template being processed?"
 310 The \f(CW\*(C`template\*(C'\fR variable contains a reference to the
 311 Template::Document object for the main template you're processing
 312 (i.e. the one provided as the first argument to the Template \fIprocess()\fR
 313 method).  The \f(CW\*(C`name\*(C'\fR method returns its name.
 314 .PP
 315 .Vb 1
 316 \&    [% template.name %]     # e.g. index.html
 317 .Ve
 318 .Sh "How can I find out the name of the current template being processed?"
 319 .IX Subsection "How can I find out the name of the current template being processed?"
 320 The \f(CW\*(C`template\*(C'\fR variable always references the \fImain\fR template being processed.
 321 So even if you call [% \s-1INCLUDE\s0 header %], and that calls [% \s-1INCLUDE\s0 menu %],
 322 the \f(CW\*(C`template\*(C'\fR variable will be unchanged.
 323 .PP
 324 index.html:
 325 .PP
 326 .Vb 2
 327 \&    [% template.name  %]     # index.html
 328 \&    [% INCLUDE header %]
 329 .Ve
 330 .PP
 331 header:
 332 .PP
 333 .Vb 2
 334 \&    [% template.name  %]     # index.html
 335 \&    [% INCLUDE menu   %]
 336 .Ve
 337 .PP
 338 menu:
 339 .PP
 340 .Vb 1
 341 \&    [% template.name  %]     # index.html
 342 .Ve
 343 .PP
 344 In constrast, the \f(CW\*(C`component\*(C'\fR variable always references the \fIcurrent\fR
 345 template being processed.
 346 .PP
 347 index.html
 348 .PP
 349 .Vb 2
 350 \&    [% component.name %]     # index.html
 351 \&    [% INCLUDE header %]
 352 .Ve
 353 .PP
 354 header:
 355 .PP
 356 .Vb 2
 357 \&    [% component.name %]     # header
 358 \&    [% INCLUDE menu   %]
 359 .Ve
 360 .PP
 361 menu:
 362 .PP
 363 .Vb 1
 364 \&    [% component.name  %]     # menu
 365 .Ve
 366 .Sh "How do I print the modification time of the template or component?"
 367 .IX Subsection "How do I print the modification time of the template or component?"
 368 The \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variables reference the main template
 369 and the current template being processed (see previous questions).
 370 The \f(CW\*(C`modtime\*(C'\fR method returns the modification time of the
 371 corresponding template file as a number of seconds since the Unix
 372 epoch (00:00:00 \s-1GMT\s0 1st January 1970).
 373 .PP
 374 This number doesn't mean much to anyone (except perhaps serious Unix
 375 geeks) so you'll probably want to use the Date plugin to format it for
 376 human consumption.
 377 .PP
 378 .Vb 2
 379 \&    [% USE Date %]
 380 \&    [% template.name %] last modified [% Date.format(template.modtime) %]
 381 .Ve
 382 .Sh "How can I configure variables on a per-request basis?"
 383 .IX Subsection "How can I configure variables on a per-request basis?"
 384 One easy way to achieve this is to define a single \f(CW\*(C`PRE_PROCESS\*(C'\fR template
 385 which loads in other configuration files based on variables defined or other
 386 conditions.
 387 .PP
 388 For example, my setup usually looks something like this:
 389 .PP
 390 .Vb 1
 391 \&    PRE_PROCESS => 'config/main'
 392 .Ve
 393 .PP
 394 config/main:
 395 .PP
 396 .Vb 2
 397 \&    [%  DEFAULT  style   = 'text'
 398 \&                 section =  template.section or 'home';
 399 .Ve
 400 .PP
 401 .Vb 7
 402 \&        PROCESS  config/site
 403 \&              +  config/urls
 404 \&              +  config/macros
 405 \&              + "config/style/$style"
 406 \&              + "config/section/$section"
 407 \&              + ...
 408 \&    %]
 409 .Ve
 410 .PP
 411 This allows me to set a single 'style' variable to control which config
 412 file gets pre-processed to set my various style options (colours, img paths,
 413 etc).  For example:
 414 .PP
 415 config/style/basic:
 416 .PP
 417 .Vb 2
 418 \&    [%  style = {
 419 \&            name = style    # save existing 'style' var as 'style.name'
 420 .Ve
 421 .PP
 422 .Vb 6
 423 \&            # define various other style variables....
 424 \&            col = {
 425 \&                back => '#ffffff'
 426 \&                text => '#000000'
 427 \&                    # ...etc...
 428 \&            }
 429 .Ve
 430 .PP
 431 .Vb 3
 432 \&            logo = {
 433 \&                    # ...etc...
 434 \&            }
 435 .Ve
 436 .PP
 437 .Vb 3
 438 \&            # ...etc...
 439 \&        }
 440 \&    %]
 441 .Ve
 442 .PP
 443 Each source template can declare which section it's in via a \s-1META\s0
 444 directive:
 445 .PP
 446 .Vb 5
 447 \&  [% META
 448 \&       title   = 'General Information'
 449 \&       section = 'info'
 450 \&  %]
 451 \&  ...
 452 .Ve
 453 .PP
 454 This controls which section configuration file gets loaded to set various
 455 other variables for defining the section title, menu, etc.
 456 .PP
 457 config/section/info:
 458 .PP
 459 .Vb 7
 460 \&    [%  section = {
 461 \&            name   = section  # save 'section' var as 'section.name'
 462 \&            title  = 'Information'
 463 \&            menu   = [ ... ]
 464 \&            # ...etc...
 465 \&        }
 466 \&    %]
 467 .Ve
 468 .PP
 469 This illustrates the basic principal but you can extend it to perform
 470 pretty much any kind of per-document initialisation that you require.
 471 .Sh "Why do I get rubbish for my utf\-8 templates?"
 472 .IX Subsection "Why do I get rubbish for my utf-8 templates?"
 473 First of all, make sure that your template files define a Byte Order
 474 Mark <http://en.wikipedia.org/wiki/Byte_Order_Mark>
 475 .PP
 476 If you for some reason don't want to add \s-1BOM\s0 to your templates, you can
 477 force Template to use a particular encoding (e.g. \f(CW\*(C`utf8\*(C'\fR) for your
 478 templates with the \f(CW\*(C`ENCODING\*(C'\fR option.
 479 .PP
 480 .Vb 3
 481 \&    my $template = Template\->new({
 482 \&        ENCODING => 'utf8'
 483 \&    });
 484 .Ve
 485 .SH "Questions About This FAQ"
 486 .IX Header "Questions About This FAQ"
 487 .Sh "Why is this \s-1FAQ\s0 so short?"
 488 .IX Subsection "Why is this FAQ so short?"
 489 Because we don't have anyone maintaining it.
 490 .Sh "Can I help?"
 491 .IX Subsection "Can I help?"
 492 Yes please :\-)