diff options
Diffstat (limited to 'lib/Template/Manual/Intro.pod')
| -rw-r--r-- | lib/Template/Manual/Intro.pod | 295 |
1 files changed, 0 insertions, 295 deletions
diff --git a/lib/Template/Manual/Intro.pod b/lib/Template/Manual/Intro.pod deleted file mode 100644 index c50c9e8..0000000 --- a/lib/Template/Manual/Intro.pod +++ /dev/null @@ -1,295 +0,0 @@ -#============================================================= -*-perl-*- -# -# Template::Manual::Intro -# -# DESCRIPTION -# This section provides a general introduction to the Template -# Toolkit, giving a quick overview of features, examples of template -# directives and use of the Template.pm module. It also described the -# basic concept underlying the toolkit: the separation of -# presentation elements from application logic and data. -# -# 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 -# -# -#======================================================================== - - -#------------------------------------------------------------------------ -# 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::Manual::Intro - Introduction to the Template Toolkit - -=head1 DESCRIPTION - -This section provides a general introduction to the Template Toolkit, -giving a quick overview of features, examples of template directives -and use of the Template.pm module. It also described the basic concept -underlying the toolkit: the separation of presentation elements from -application logic and data. - -The Template Toolkit is a collection of modules which implement a -fast, flexible, powerful and extensible template processing system. -It was originally designed and remains primarily useful for generating -dynamic web content, but it can be used equally well for processing -any kind of text documents. This POD documentation is all generated -using the Template Toolkit batch mode utility F<ttree>, for example. - -At the simplest level it provides an easy way to process template -files, filling in embedded variable references with their equivalent -values. - - Dear [% name %], - - It has come to our attention that your account is in - arrears to the sum of [% debt %]. - - Please settle your account before [% deadline %] or we - will be forced to revoke your Licence to Thrill. - - The Management. - -By default, template directives are embedded within the character -sequences '[%' ... '%]' but you can change these and various other -options to configure how the Template Toolkit looks, feels and works. -You can set the INTERPOLATE option, for example, if you prefer to -embed your variables in Perl style: - - Dear $name, - - It has come to our attention that your account is in - arrears to the sum of $debt. - ... - -=head2 Template.pm - -The Template.pm module is the front end to the Template Toolkit, -providing access to the full range of functionality through a single -module with a simple interface. It loads the other modules as -required and instantiates a default set of objects to handle -subsequent template processing requests. Configuration parameters may -be passed to the Template.pm constructor, new(), which are then used -to configure the underlying objects. - - use Template; - - my $tt = Template->new({ - INCLUDE_PATH => '/usr/local/templates', - INTERPOLATE => 1, - }) || die "$Template::ERROR\n"; - -The Template object implements a process() method for processing template -files or text. The name of the input template (or various other sources) -is passed as the first argument, followed by a reference to a hash array -of variable definitions for substitution in the template. - - my $vars = { - name => 'Count Edward van Halen', - debt => '3 riffs and a solo', - deadline => 'the next chorus', - }; - - $tt->process('letters/overdrawn', $vars) - || die $tt->error(), "\n"; - - -The process() method returns true (1) on success and prints the -template output to STDOUT, by default. On error, the process() method -returns false (undef). The error() method can then be called to -retrieve details of the error. - -=head2 Component Based Content Construction - -A number of special directives are provided, such as INSERT, INCLUDE -and PROCESS, which allow content to be built up from smaller template -components. This permits a modular approach to building a web site or -other content repository, promoting reusability, cross-site -consistency, ease of construction and subsequent maintenance. Common -elements such as headers, footers, menu bars, tables, and so on, can -be created as separate template files which can then be processed into -other documents as required. All defined variables are inherited by -these templates along with any additional "local" values specified. - - [% PROCESS header - title = "The Cat Sat on the Mat" - %] - - [% PROCESS menu %] - - The location of the missing feline has now been established. - Thank you for your assistance. - - [% INSERT legal/disclaimer %] - - [% PROCESS footer %] - -You can also define a template as a BLOCK within the same file and -PROCESS it just like any other template file. This can be invaluable -for building up repetitive elements such as tables, menus, etc. - - [% BLOCK tabrow %] - <tr><td>[% name %]</td><td>[% email %]</td></tr> - [% END %] - - <table> - [% PROCESS tabrow name="tom" email="tom@here.org" %] - [% PROCESS tabrow name="dick" email="disk@there.org" %] - [% PROCESS tabrow name="larry" email="larry@where.org" %] - </table> - -=head2 Data and Code Binding - -One of the key features that sets the Template Toolkit apart from -other template processors is the ability to bind template variables to -any kind of Perl data: scalars, lists, hash arrays, sub-routines and -objects. - - my $vars = { - root => 'http://here.com/there', - menu => [ 'modules', 'authors', 'scripts' ], - client => { - name => 'Doctor Joseph von Satriani', - id => 'JVSAT', - }, - checkout => sub { my $total = shift; ...; return $something }, - shopcart => My::Cool::Shopping::Cart->new(), - }; - -The Template Toolkit will automatically Do The Right Thing to access -the data in an appropriate manner to return some value which can then -be output. The dot operator '.' is used to access into lists and -hashes or to call object methods. The FOREACH directive is provided for -iterating through lists, and various logical tests are available using -directives such as IF, UNLESS, ELSIF, ELSE, SWITCH, CASE, etc. - - [% FOREACH section = menu %] - <a href="[% root %]/[% section %]/index.html">[% section %]</a> - [% END %] - - <b>Client</a>: [% client.name %] (id: [% client.id %]) - - [% IF shopcart.nitems %] - Your shopping cart contains the following items: - <ul> - [% FOREACH item = shopcart.contents %] - <li>[% item.name %] : [% item.qty %] @ [% item.price %] - [% END %] - </ul> - - [% checkout(shopcart.total) %] - - [% ELSE %] - No items currently in shopping cart. - [% END %] - -=head2 Advanced Features: Filters, Macros, Exceptions, Plugins - -The Template Toolkit also provides a number of additional directives -for advanced processing and programmatical functionality. It supports -output filters (FILTER), allows custom macros to be defined (MACRO), -has a fully-featured exception handling system (TRY, THROW, CATCH, -FINAL) and supports a plugin architecture (USE) which allows special -plugin modules and even regular Perl modules to be loaded and used -with the minimum of fuss. The Template Toolkit is "just" a template -processor but you can trivially extend it to incorporate the -functionality of any Perl module you can get your hands on. Thus, it -is also a scalable and extensible template framework, ideally suited -for managing the presentation layer for application servers, content -management systems and other web applications. - -=head2 Separating Presentation and Application Logic - -Rather than embedding Perl code or some other scripting language -directly into template documents, it encourages you to keep functional -components (i.e. Perl code) separate from presentation components -(e.g. HTML templates). The template variables provide the interface -between the two layers, allowing data to be generated in code and then -passed to a template component for displaying (pipeline model) or for -sub-routine or object references to be bound to variables which can -then be called from the template as and when required (callback -model). - -The directives that the Template Toolkit provide implement their own -mini programming language, but they're not really designed for -serious, general purpose programming. Perl is a far more appropriate -language for that. If you embed application logic (e.g. Perl or other -scripting language fragments) in HTML templates then you risk losing -the clear separation of concerns between functionality and -presentation. It becomes harder to maintain the two elements in -isolation and more difficult, if not impossible, to reuse code or -presentation elements by themselves. It is far better to write your -application code in separate Perl modules, libraries or scripts and -then use templates to control how the resulting data is presented as -output. Thus you should think of the Template Toolkit language as a -set of layout directives for displaying data, not calculating it. - -Having said that, the Template Toolkit doesn't force you into one -approach or the other. It attempts to be pragmatic rather than -dogmatic in allowing you to do whatever best gets the job done. -Thus, if you enable the EVAL_PERL option then you can happily embed -real Perl code in your templates within PERL ... END directives. - -=head2 Performance - -The Template Toolkit uses a fast YACC-like parser which compiles -templates into Perl code for maximum runtime efficiency. It also has -an advanced caching mechanism which manages in-memory and on-disk -(i.e. persistent) versions of compiled templates. The modules that -comprise the toolkit are highly configurable and the architecture -around which they're built is designed to be extensible. The Template -Toolkit provides a powerful framework around which content creation -and delivery systems can be built while also providing a simple -interface through the Template front-end module for general use. - -=head1 AUTHOR - -Andy Wardley E<lt>abw@andywardley.comE<gt> - -L<http://www.andywardley.com/|http://www.andywardley.com/> - - - - -=head1 VERSION - -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: |