* Move files to trunk

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: