{ "content": [ { "type": "text", "text": "# Template::Manual::Intro (perldoc)\n\n## NAME\n\nTemplate::Manual::Intro - Introduction to the Template Toolkit\n\n## Sections\n\n- **NAME**\n- **Introduction**\n- **The Template Perl Module** (1 subsections)\n- **Component Based Content Construction**\n- **Data and Code Binding**\n- **Advanced Features: Filters, Macros, Exceptions, Plugins**\n- **Separating Presentation and Application Logic**\n- **Performance**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Template::Manual::Intro", "section": "", "mode": "perldoc", "summary": "Template::Manual::Intro - Introduction to the Template Toolkit", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "Introduction", "lines": 29, "subsections": [] }, { "name": "The Template Perl Module", "lines": 28, "subsections": [ { "name": "error", "lines": 1 } ] }, { "name": "Component Based Content Construction", "lines": 35, "subsections": [] }, { "name": "Data and Code Binding", "lines": 41, "subsections": [] }, { "name": "Advanced Features: Filters, Macros, Exceptions, Plugins", "lines": 10, "subsections": [] }, { "name": "Separating Presentation and Application Logic", "lines": 23, "subsections": [] }, { "name": "Performance", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Template::Manual::Intro - Introduction to the Template Toolkit\n", "subsections": [] }, "Introduction": { "content": "The Template Toolkit is a collection of Perl modules which implement a fast, flexible, powerful\nand extensible template processing system. It is most often used for generating dynamic web\ncontent, although it can be used equally well for processing any kind of text documents.\n\nAt the simplest level it provides an easy way to process template files, filling in embedded\nvariable references with their equivalent values. Here's an example of a template.\n\nDear [% name %],\n\nIt has come to our attention that your account is in\narrears to the sum of [% debt %].\n\nPlease settle your account before [% deadline %] or we\nwill be forced to revoke your Licence to Thrill.\n\nThe Management.\n\nBy default, template directives are embedded within the character sequences \"[%\" ... \"%]\" but\nyou can change these and various other options to configure how the Template Toolkit looks,\nfeels and works. You can set the \"INTERPOLATE\" option, for example, if you prefer to embed your\nvariables in Perl style:\n\nDear $name,\n\nIt has come to our attention that your account is in\narrears to the sum of $debt.\n\n...etc...\n", "subsections": [] }, "The Template Perl Module": { "content": "The Template Perl module is the front end to the Template Toolkit for Perl programmers,\nproviding access to the full range of functionality through a single module with a simple\ninterface. It loads the other modules as required and instantiates a default set of objects to\nhandle subsequent template processing requests. Configuration parameters may be passed to the\nTemplate constructor method, new(), which are then used to configure the generate object.\n\nuse Template;\n\nmy $tt = Template->new({\nINCLUDEPATH => '/usr/local/templates',\nINTERPOLATE => 1,\n}) || die \"$Template::ERROR\\n\";\n\nThe Template object implements a process() method for processing template files or text. The\nname of the input template (or various other sources) is passed as the first argument, followed\nby a reference to a hash array of variable definitions for substitution in the template.\n\nmy $vars = {\nname => 'Count Edward van Halen',\ndebt => '3 riffs and a solo',\ndeadline => 'the next chorus',\n};\n\n$tt->process('letters/overdrawn', $vars)\n|| die $tt->error(), \"\\n\";\n\nThe process() method returns a true value (1) on success and prints the template output to\n\"STDOUT\", by default. On error, the process() method returns a false value (\"undef\"). The", "subsections": [ { "name": "error", "content": "" } ] }, "Component Based Content Construction": { "content": "A number of special directives are provided, such as \"INSERT\", \"INCLUDE\" and \"PROCESS\", which\nallow content to be built up from smaller template components. This permits a modular approach\nto building a web site or other content repository, promoting reusability, cross-site\nconsistency, ease of construction and subsequent maintenance. Common elements such as headers,\nfooters, menu bars, tables, and so on, can be created as separate template files which can then\nbe processed into other documents as required. All defined variables are inherited by these\ntemplates along with any additional \"local\" values specified.\n\n[% PROCESS header\ntitle = \"The Cat Sat on the Mat\"\n%]\n\n[% PROCESS menu %]\n\nThe location of the missing feline has now been established.\nThank you for your assistance.\n\n[% INSERT legal/disclaimer %]\n\n[% PROCESS footer %]\n\nYou can also define a template as a BLOCK within the same file and PROCESS it just like any\nother template file. This can be invaluable for building up repetitive elements such as tables,\nmenus, etc.\n\n[% BLOCK tabrow %]\n[% name %][% email %]\n[% END %]\n\n\n[% PROCESS tabrow name=\"tom\" email=\"tom@here.org\" %]\n[% PROCESS tabrow name=\"dick\" email=\"disk@there.org\" %]\n[% PROCESS tabrow name=\"larry\" email=\"larry@where.org\" %]\n
\n", "subsections": [] }, "Data and Code Binding": { "content": "One of the key features that sets the Template Toolkit apart from other template processors is\nthe ability to bind template variables to any kind of Perl data: scalars, lists, hash arrays,\nsub-routines and objects.\n\nmy $vars = {\nroot => 'http://here.com/there',\nmenu => [ 'modules', 'authors', 'scripts' ],\nclient => {\nname => 'Doctor Joseph von Satriani',\nid => 'JVSAT',\n},\ncheckout => sub { my $total = shift; ...; return $something },\nshopcart => My::Cool::Shopping::Cart->new(),\n};\n\nThe Template Toolkit will automatically Do The Right Thing to access the data in an appropriate\nmanner to return some value which can then be output. The dot operator '\".\"' is used to access\ninto lists and hashes or to call object methods. The \"FOREACH\" directive is provided for\niterating through lists, and various logical tests are available using directives such as \"IF\",\n\"UNLESS\", \"ELSIF\", \"ELSE\", \"SWITCH\", \"CASE\", etc.\n\n[% FOREACH section = menu %]\n[% section %]\n[% END %]\n\nClient: [% client.name %] (id: [% client.id %])\n\n[% IF shopcart.nitems %]\nYour shopping cart contains the following items:\n\n\n[% checkout(shopcart.total) %]\n\n[% ELSE %]\nNo items currently in shopping cart.\n[% END %]\n", "subsections": [] }, "Advanced Features: Filters, Macros, Exceptions, Plugins": { "content": "The Template Toolkit also provides a number of additional directives for advanced processing and\nprogrammatical functionality. It supports output filters (FILTER), allows custom macros to be\ndefined (MACRO), has a fully-featured exception handling system (TRY, THROW, CATCH, FINAL) and\nsupports a plugin architecture (USE) which allows special plugin modules and even regular Perl\nmodules to be loaded and used with the minimum of fuss. The Template Toolkit is \"just\" a\ntemplate processor but you can trivially extend it to incorporate the functionality of any Perl\nmodule you can get your hands on. Thus, it is also a scalable and extensible template framework,\nideally suited for managing the presentation layer for application servers, content management\nsystems and other web applications.\n", "subsections": [] }, "Separating Presentation and Application Logic": { "content": "Rather than embedding Perl code or some other scripting language directly into template\ndocuments, it encourages you to keep functional components (i.e. Perl code) separate from\npresentation components (e.g. HTML templates). The template variables provide the interface\nbetween the two layers, allowing data to be generated in code and then passed to a template\ncomponent for displaying (pipeline model) or for sub-routine or object references to be bound to\nvariables which can then be called from the template as and when required (callback model).\n\nThe directives that the Template Toolkit provide implement their own mini programming language,\nbut they're not really designed for serious, general purpose programming. Perl is a far more\nappropriate language for that. If you embed application logic (e.g. Perl or other scripting\nlanguage fragments) in HTML templates then you risk losing the clear separation of concerns\nbetween functionality and presentation. It becomes harder to maintain the two elements in\nisolation and more difficult, if not impossible, to reuse code or presentation elements by\nthemselves. It is far better to write your application code in separate Perl modules, libraries\nor scripts and then use templates to control how the resulting data is presented as output. Thus\nyou should think of the Template Toolkit language as a set of layout directives for displaying\ndata, not calculating it.\n\nHaving said that, the Template Toolkit doesn't force you into one approach or the other. It\nattempts to be pragmatic rather than dogmatic in allowing you to do whatever best gets the job\ndone. Thus, if you enable the EVALPERL option then you can happily embed real Perl code in your\ntemplates within PERL ... END directives.\n", "subsections": [] }, "Performance": { "content": "The Template Toolkit uses a fast YACC-like parser which compiles templates into Perl code for\nmaximum runtime efficiency. It also has an advanced caching mechanism which manages in-memory\nand on-disk (i.e. persistent) versions of compiled templates. The modules that comprise the\ntoolkit are highly configurable and the architecture around which they're built is designed to\nbe extensible. The Template Toolkit provides a powerful framework around which content creation\nand delivery systems can be built while also providing a simple interface through the Template\nfront-end module for general use.\n", "subsections": [] } } } }