Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tenjin::Template(3)   User Contributed Perl Documentation  Tenjin::Template(3)

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:

       o   "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.

       o   "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}".

       o   "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.

       o   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/>.

       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.

perl v5.32.1			  2011-03-29		   Tenjin::Template(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | INTERNAL METHODS | SEE ALSO | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tenjin::Template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help