local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Modules.pod

   1 #============================================================= -*-perl-*-
   2 #
   3 # Template::Modules
   4 #
   5 # DESCRIPTION
   6 #
   7 # AUTHOR
   8 #   Andy Wardley  <abw@wardley.org>
   9 #
  10 # COPYRIGHT
  11 #   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
  12 #
  13 #   This module is free software; you can redistribute it and/or
  14 #   modify it under the same terms as Perl itself.
  15 #
  16 #========================================================================
  17
  18 =head1 NAME
  19
  20 Template::Modules - Template Toolkit Modules
  21
  22 =head1 Template Toolkit Modules
  23
  24 This documentation provides an overview of the different modules that
  25 comprise the Template Toolkit.
  26
  27 =head2 Template
  28
  29 The L<Template> module is the front-end to the Template Toolkit for
  30 Perl programmers.
  31
  32     use Template;
  33     my $tt = Template->new();
  34     $tt->process('hello.html', message => 'Hello World');
  35
  36 =head2 Template::Base
  37
  38 The L<Template::Base> module implements a base class from which the other
  39 Template Toolkit modules are derived.  It implements common functionality
  40 for creating objects, error reporting, debugging, and so on.
  41
  42 =head2 Template::Config
  43
  44 The L<Template::Config> module defines the configuration of the Template
  45 Toolkit for your system. It is an example of a I<factory module> which is
  46 responsible for instantiating the various other modules used in the Template
  47 Toolkit.
  48
  49 For example, the L<Template::Config> module defines the C<$STASH> package
  50 variable which indicates which version of the L<Template::Stash> you are
  51 using by default.  If you elected to use the faster L<XS|Template::Stash::XS>
  52 stash when you installed the Template Toolkit, then this will be set as:
  53
  54     $STASH = 'Template::Stash::XS';
  55
  56 Otherwise you'll get the regular L<Perl|Template::Stash> stash:
  57
  58     $STASH = 'Template::Stash';
  59
  60 This approach means that other parts of the Template Toolkit don't have to
  61 worry about which stash you're using.  They just ask the L<Template::Config>
  62 module to create a stash of the right kind.
  63
  64 =head2 Template::Constants
  65
  66 The L<Template::Constants> defines a number of constants that are used by
  67 the Template Toolkit.
  68
  69 For example, the C<:chomp> tagset defines the C<CHOMP_???> constants that
  70 can be used with the C<PRE_CHOMP> and C<POST_CHOMP> configuration options.
  71
  72     use Template::Constants ':chomp';
  73     my $tt = Template->new({
  74         PRE_CHOMP => CHOMP_COLLAPSE,
  75     });
  76
  77 =head2 Template::Context
  78
  79 The L<Template::Context> module defines a runtime context in which templates
  80 are processed. A context keeps track of all the templates, variables, plugins,
  81 and other resources that are available (either directly or through delegate
  82 objects) and provides methods to fetch, store, and perform various operations
  83 on them.
  84
  85 =head2 Template::Document
  86
  87 The L<Template::Document> module implements a compiled template document
  88 object.  This is generated by the L<Template::Parser> module.
  89
  90 =head2 Template::Exception
  91
  92 The L<Template::Exception> module implements an exception object which
  93 is used for runtime error reporting.
  94
  95 =head2 Template::Filters
  96
  97 The L<Template::Filters> module implements a filter provider.  It includes
  98 the core collection of filters that can be used via the C<FILTER> directive.
  99
 100 =head2 Template::Iterator
 101
 102 The L<Template::Iterator> module implements a data iterator which steps
 103 through each item in a list in turn.  It is used by the C<FOREACH> directive.
 104 Within a C<FOREACH> block, the C<loop> variable always references the
 105 current iterator object.
 106
 107     [%  FOREACH item IN list;
 108           IF loop.first;
 109              # first item in loop
 110           ELSIF loop.last;
 111              # last item in loop
 112           ELSE;
 113              # any other item in loop
 114           END;
 115         END
 116     %]
 117
 118 =head2 Template::Namespace::Constants
 119
 120 The L<Template::Namespace::Constants> module is used internally to represent
 121 constants. These can be resolved immediately at the point that a template is
 122 compiled.
 123
 124 =head2 Template::Parser
 125
 126 The L<Template::Parser> module is used to parse a source template and turn it
 127 into Perl code which can be executed.
 128
 129 =head2 Template::Plugin
 130
 131 The L<Template::Plugin> module is a base class for Template Toolkit plugins
 132 that can be loaded on demand from within a template using the C<USE> directive.
 133
 134 =head2 Template::Plugins
 135
 136 The L<Template::Plugins> module is the plugins provider.  It loads and prepares
 137 plugins as and when they are requested from within a template.
 138
 139 =head2 Template::Provider
 140
 141 The L<Template::Provider> module is responsible for loading, compiling and
 142 caching templates.
 143
 144 =head2 Template::Service
 145
 146 The L<Template::Service> module implements a service layer that sits just
 147 behind the L<Template> module, and just in front of a L<Template::Context>. It
 148 handles each request to process a template (forwarded from the L<Template>
 149 module). It adds any headers and/or footers (specified via the C<PRE_PROCESS>
 150 and C<POST_PROCESS> options), applies any wrapper (the C<WRAPPER> option) and
 151 catches any errors returned (the C<ERRORS> option).
 152
 153 =head2 Template::Stash
 154
 155 The L<Template::Stash> module is used to fetch and store template variables.
 156 It implements all of the magic associated with the dot operator.
 157
 158 =head2 Template::Stash::XS
 159
 160 The L<Template::Stash::XS> module is a high-speed implementation of
 161 L<Template::Stash> written in C.
 162
 163 =head2 Template::Test
 164
 165 The L<Template::Test> module is used to automate the Template Toolkit
 166 test scripts.
 167
 168 =cut
 169
 170 # Local Variables:
 171 # mode: perl
 172 # perl-indent-level: 4
 173 # indent-tabs-mode: nil
 174 # End:
 175 #
 176 # vim: expandtab shiftwidth=4: