NAME

       Tenjin::Template - A Tenjin template object, either built from a file or from memory.

VERSION

       version 0.070001

SYNOPSIS

               # mostly used internally, but you can manipulate
               # templates like so

               my $template = Tenjin::Template->new('/path/to/templates/template.html');
               my $context = { scalar => 'scalar', arrayref => ['one', 2, "3"] };
               $template->render($context);

DESCRIPTION

       This module is in charge of the task of compiling Tenjin templates.  Templates in Tenjin
       are compiled into standard Perl code (combined with any Perl code used inside the
       templates themselves). Rendering a template means "eval"uating that Perl code and
       returning its output.

       The Tenjin engine reads a template file or a template string, and creates a Template
       object from it. Then the object compiles itself by traversing the template, parsing Tenjin
       macros like 'include' and 'start_capture', replaces Tenjin expressions (i.e. "[== $expr
       =]" or "[= $expr =]") with the appropriate Perl code, etc. This module ties a template
       object with a context object, but all context manipulation (and the actual "eval"uation of
       the Perl code) is done by Tenjin::Context.

       If you're planning on using this module by itself (i.e. without the Tenjin engine), keep
       in mind that template caching and layout templates are not handled by this module.

METHODS

   new( [$filename, \%opts] )
       Creates a new Tenjin::Template object, possibly from a file on the file system (in which
       case $filename must be provided and be an absolute path to a template file). Optionally, a
       hash-ref of options can be passed to set some customizations. Available options are
       'escapefunc', which will be in charge of escaping expressions (from "[= $expr =]") instead
       of the internal method (which uses HTML::Entities); and 'rawclass', which can be used to
       prevent variables and objects of a certain class from being escaped, in which case the
       variable must be a hash-ref that has a key named 'str', which will be used instead. So,
       for example, if you have a variable named $var which is a hash-ref, and 'rawclass' is set
       as 'HASH', then writing "[= $var =]" on your templates will replace $var with
       "$var->{str}".

   render( [$_context] )
       Renders the template, possibly with a context hash-ref, and returns the rendered output.
       If errors have occured when rendering the template (which might happen since templates
       have and are Perl code), then this method will croak.

INTERNAL METHODS

   convert_file( $filename )
       Receives an absolute path to a template file, converts that file to Perl code by calling
       convert() and returns that code.

   convert( $input, [$filename] )
       Receives a text of a template (i.e. the template itself) and possibly an absolute path to
       the template file (if the template comes from a file), and converts the template into Perl
       code, which is later "eval"uated for rendering. Conversion is done by parsing the
       statements in the template (see parse_stmt()).

   compile_stmt_pattern( $pl )
       Receives a string which denotes the Perl code delimiter which is used inside templates.
       Tenjin uses '"<?pl ... ?>"' and '"<?PL ... ?>"' (the latter for preprocessing), so $pl
       will be 'pl'. This method returns a tranlsation regular expression which will be used for
       reading embedded Perl code.

   stmt_pattern
       Returns the default pattern (which uses 'pl') with the previous_method.

   expr_pattern()
       Defines how expressions are written in Tenjin templates ("[== $expr =]" and "[= $expr
       =]").

   parse_stmt( $bufref, $input )
       Receives a buffer which is used for saving a template's expressions and the template's
       text, parses all expressions in the templates and pushes them to the buffer.

   hook_stmt( $stmt )
   expand_macro( $funcname, $arg )
       This method is in charge of invoking macro functions which might be used inside templates.
       The following macros are available:

       •   "include( $filename )"

           Includes another template, whose name is $filename, inside the current template. The
           included template will be placed inside the template as if they were one unit, so the
           context variable applies to both.

       •   "start_capture( $name )" and "end_capture()"

           Tells Tenjin to capture the output of the rendered template from the point where
           "start_capture()" was called to the point where "end_capture()" was called. You must
           provide a name for the captured portion, which will be made available in the context
           as "$_context->{$name}" for immediate usage. Note that the captured portion will not
           be printed unless you do so explicilty with "$_context->{$name}".

       •   "start_placeholder( $var )" and "end_placeholder()"

           This is a special method which can be used for making your templates a bit cleaner.
           Suppose your context might have a variable whose name is defined in $var. If that
           variable exists in the context, you simply want to print it, but if it's not, you want
           to print and/or perform other things. In that case you can call "start_placeholder(
           $var )" with the name of the context variable you want printed, and if it's not,
           anything you do between "start_placeholder()" and "end_placeholder()" will be printed
           instead.

       •   echo( $exr )

           Just prints the provided expression. You might want to use it if you're a little too
           comfortable with PHP.

   get_expr_and_escapeflag( $not_escape, $expr, $delete_newline )
   parse_expr( $bufref, $input )
   start_text_part( $bufref )
   stop_text_part( $bufref )
   add_text( $bufref, $text )
   add_stmt( $bufref, $stmt )
   add_expr( $bufref, $expr, $flag_escape )
   defun( $funcname, @args )
   compile()
   escaped_expr( $expr )
       Receives a Perl expression (from "[= $expr =]") and escapes it. This will happen in one of
       three ways: with the escape function defined in "$opts->{escapefunc}" (if defined), with a
       scalar string (if "$opts->{rawclass}" is defined), or with "escape_xml()" from
       Tenjin::Util, which uses HTML::Entites.

   _read_file( $filename, [$lock_required] )
       Receives an absolute path to a template file, reads its content and returns it. If
       $lock_required is passed (and has a true value), the file will be locked for reading.

   _write_file( $filename, $content, [$lock_required] )
       Receives an absolute path to a template file and the templates contents, and creates the
       file (or truncates it, if existing) with that contents.  If $lock_required is passed (and
       has a true value), the file will be locked exclusively when writing.

SEE ALSO

       Tenjin.

AUTHOR

       The CPAN version of Tenjin was forked by Ido Perlmuter <ido at ido50.net> from version
       0.0.2 of the original plTenjin, which is developed by Makoto Kuwata at
       http://www.kuwata-lab.com/tenjin/ <http://www.kuwata-lab.com/tenjin/>.

       Development of Tenjin is done with github at <http://github.com/ido50/Tenjin>.

LICENSE AND COPYRIGHT

       Tenjin is licensed under the MIT license.

               Copyright (c) 2007-2010 the aforementioned authors.

               Permission is hereby granted, free of charge, to any person obtaining
               a copy of this software and associated documentation files (the
               "Software"), to deal in the Software without restriction, including
               without limitation the rights to use, copy, modify, merge, publish,
               distribute, sublicense, and/or sell copies of the Software, and to
               permit persons to whom the Software is furnished to do so, subject to
               the following conditions:

               The above copyright notice and this permission notice shall be
               included in all copies or substantial portions of the Software.

               THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
               EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
               MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
               NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
               LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
               OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
               WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.