diff options
Diffstat (limited to 'lib/Template/FAQ.pod')
| -rw-r--r-- | lib/Template/FAQ.pod | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/lib/Template/FAQ.pod b/lib/Template/FAQ.pod new file mode 100644 index 0000000..0807ace --- /dev/null +++ b/lib/Template/FAQ.pod @@ -0,0 +1,329 @@ +#============================================================= -*-perl-*- +# +# Template::FAQ +# +# DESCRIPTION +# This is the Frequently Asked Questions list for the Template +# Toolkit. More accurately, it's a very thin placeholder for where +# the FAQ will soon be. +# +# AUTHOR +# Andy Wardley <abw@andywardley.com> +# +# COPYRIGHT +# Copyright (C) 1996-2001 Andy Wardley. All Rights Reserved. +# Copyright (C) 1998-2001 Canon Research Centre Europe Ltd. +# +# This module is free software; you can redistribute it and/or +# modify it under the same terms as Perl itself. +# +# REVISION +# 2.69 +# +#======================================================================== + + +#------------------------------------------------------------------------ +# IMPORTANT NOTE +# This documentation is generated automatically from source +# templates. Any changes you make here may be lost. +# +# The 'docsrc' documentation source bundle is available for download +# from http://www.template-toolkit.org/docs.html and contains all +# the source templates, XML files, scripts, etc., from which the +# documentation for the Template Toolkit is built. +#------------------------------------------------------------------------ + +=head1 NAME + +Template::FAQ - Frequently Asked Questions about the Template Toolkit + +=head1 DESCRIPTION + +This is the Frequently Asked Questions list for the Template Toolkit. +More accurately, it's a very thin placeholder for where the FAQ will +soon be. + + +=head1 Template Toolkit Language + +=head2 Why doesn't [% a = b IF c %] work as expected? + +Because the parser interprets it as + + [% a = (b IF c) %] + +Do this instead: + + [% SET a = b IF c %] + +=head2 If I'm using TT to write out a TT template, is there a good way to escape [% and %]? + +You can do this: + + [% stag = "[\%" + etag = "%\]" + %] + +and then: + + [% stag; 'hello'; etag %] + +Or something like: + + [% TAGS [- -] %] + [- INCLUDE foo -] # is a directive + [% INCLUDE foo %] # not a directive, just plain text, passed through + +=head2 How do I iterate over a hash? + +This is covered in the L<Template::Manual::VMethods|VMethods> section +of the manual page. A list of all the keys that are in the hash can +be obtained with the 'keys' virtual method. You can then iterate +over that list and by looking up each key in turn get the value. + + [% FOREACH key = product.keys %] + [% key %] => [% product.$key %] + [% END %] + +=head1 Plugins + +=head2 How do I get the Table plugin to order data across rather than down? + +Order the data into rows: + + Steve Karen Jeff + Brooklyn Nantucket Fairfax + NY MA VA + + [% USE table(data, rows=3) %] + +Then ask for each column + + [% FOREACH column = table.cols %] + +And then print each item in the column going across the output rows + + [% FOREACH item = column %] + <td>[% item %]</td> + [% END %] + +=head2 Accessing Cookies + +Jeff Boes E<lt>jboes@nexcerpt.comE<gt> asks: + + Does anyone have a quick-n-dirty approach to accessing + cookies from templates? + +Jonas Liljegren answers: + + [% USE CGI %] + + <p>The value is [% CGI.cookie('cookie_name') | html %] + + +=head1 Extending the Template Toolkit + +=head2 Can I serve templates from a database? + +Short answer: yes, Chris Nandor has done this for Slash. You need to +subclass Template::Provider. See the mailing list archives for further +info. + +=head2 Can I fetch templates via http? + +To do the job properly, you should sublcass Template::Provider to +Template::Provider::HTTP and use a PREFIX_MAP option to bind the +'http' template prefix to that particular provider (you may want to +go digging around in the F<Changes> file around version 2.01 for +more info on PREFIX_MAP - it may not be properly documented anywhere +else...yet!). e.g. (untested due to lack of existing HTTP Provider +- patches welcome!). + + use Template::Provider::HTTP; + + my $file = Template::Provider( INCLUDE_PATH => [...] ); + my $http = Template::Provider::HTTP->new(...); + my $tt2 = Template->new({ + LOAD_TEMPLATES => [ $file, $http ], + PREFIX_MAP => { + file => '0', # file:foo.html + http => '1', # http:foo.html + default => '0', # foo.html => file:foo.html + } + }); + +Now a template specified as: + + [% INCLUDE foo %] + +will be served by the 'file' provider (the default). Otherwise you +can explicitly add a prefix: + + [% INCLUDE file:foo.html %] + [% INCLUDE http:foo.html %] + [% INCLUDE http://www.xyz.com/tt2/header.tt2 %] + +This same principal can be used to create a DBI template provider. e.g. + + [% INCLUDE dbi:foo.html %] + +But similarly, alas, we don't yet have a DBI provider as part of the +Template Toolkit. There has been some talk on the mailing list about +efforts to develop DBI and/or HTTP providers but as yet no-one has +stepped forward to take up the challenge... + +In the mean time, Craig's post from the mailing list has some useful +pointers on how to acheive this using existing modules: + + To: Adam Theo <adamtheo@theoretic.com> + From: Craig Barratt <craig@arraycomm.com> + Date: Fri, 18 May 2001 17:06:59 -0700 + + > i was wondering if there is anyway to fetch a file using http:// or + > ftp:// and include that? + + Here's one way. Set the LOAD_PERL option: + + use Template; + + my $template = Template->new({ + LOAD_PERL => 1 + }); + $template->process("example.tt", { stdout => *STDOUT }) + || die $template->error(); + + and then use LWP::UserAgent and HTTP::Request: + + [% + USE ua = LWP.UserAgent; + ua.proxy("http", "http://your_proxy/"); + USE req = HTTP.Request("GET", "http://www.cpan.org"); + ua.request(req).content; + -%] + + For FTP use Net::FTP: + + [% + USE ftp = Net.FTP("ftp.cpan.org"); + x = ftp.login("anonymous", "me@here.there"); + x = ftp.cwd("/"); + x = ftp.get("welcome.msg", stdout); + x = ftp.quit; + -%] + + Normally ftp.get would write the file into the current directory. + Instead we pass stdout as a second argument so that it is written + to stdout. We set stdout to STDOUT in the variables we pass to + process. + + Craig + +=head1 Miscellaneous + +=head2 How can I configure variables on a per-request basis? + +One easy way to acheive this is to define a single PRE_PROCESS template which +loads in other configuration files based on variables defined or other +conditions. + +For example, my setup usually looks something like this: + + PRE_PROCESS => 'config/main' + +config/main: + + [% DEFAULT style = 'text' + section = template.section or 'home'; + + PROCESS config/site + + config/urls + + config/macros + + "config/style/$style" + + "config/section/$section" + + ... + %] + +This allows me to set a single 'style' variable to control which config +file gets pre-processed to set my various style options (colours, img paths, +etc). For example: + +config/style/basic: + + [% style = { + name = style # save existing 'style' var as 'style.name' + + # define various other style variables.... + col = { + back => '#ffffff' + text => '#000000' + # ...etc... + } + + logo = { + # ...etc... + } + + # ...etc... + } + %] + +Each source template can declare which section it's in via a META +directive: + + [% META + title = 'General Information' + section = 'info' + %] + + ... + +This controls which section configuration file gets loaded to set various +other variables for defining the section title, menu, etc. + +config/section/info: + + [% section = { + name = section # save 'section' var as 'section.name' + title = 'Information' + menu = [ ... ] + # ...etc... + } + %] + +This illustrates the basic principal but you can extend it to perform +pretty much any kind of per-document initialisation that you require. + +=head1 AUTHOR + +Andy Wardley E<lt>abw@andywardley.comE<gt> + +L<http://www.andywardley.com/|http://www.andywardley.com/> + + + + +=head1 VERSION + +2.69, distributed as part of the +Template Toolkit version 2.13, released on 30 January 2004. + +=head1 COPYRIGHT + + Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved. + Copyright (C) 1998-2002 Canon Research Centre Europe Ltd. + +This module is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + + + +=cut + +# Local Variables: +# mode: perl +# perl-indent-level: 4 +# indent-tabs-mode: nil +# End: +# +# vim: expandtab shiftwidth=4: |