MicroMason::TemplatePath(3pm)				User Contributed Perl Documentation			     MicroMason::TemplatePath(3pm)

NAME

       Text::MicroMason::TemplatePath - Template Path Searching

SYNOPSIS

       Instead of using this class directly, pass its name to be mixed in:

	   use Text::MicroMason;
	   my $mason = Text::MicroMason->new( -TemplatePath, template_path => [ '/foo', '/bar' ] );

       Use the standard compile and execute methods to parse and evalute templates:

	 print $mason->compile( file=>$filepath )->( 'name'=>'Dave' );
	 print $mason->execute( file=>$filepath, 'name'=>'Dave' );

       Templates stored in files are searched for in the specified template_path:

	   print $mason->execute( file=>"includes/greeting.msn", 'name'=>'Charles');

       When including other files into a template you can use relative paths:

	   <& ../includes/greeting.msn, name => 'Alice' &>

       When a file is included in the template, the including template's current directory is added to the beginning of the template search path.

DESCRIPTION

       This module works similarly to the related TemplateDir mix-in. However, instead of specifying a single root which must contain all
       templates, TemplatePath allows you to specify an arrayref of directories which will be searched in order whenever a template filename must
       be resolved.

       Using a TemplatePath object, absolute filenames are used as-is. If a relative template filenames or file paths is used, every directory in
       the specified template_path is checked for the existence of the template, and the first existing template file is used.

       If a template includes another template using <& ... &>, then the including template's location is added to the beginning of the template
       search path list, for the resolution of the included template's filename. This allows the included template to be specified relative to the
       including template, but also lets the template search fall back to the configured template search path if necessary.

   Supported Attributes
       template_path
	   An array ref containing a list of directories in which to search for relative template filenames.

       strict_root
	   Optional directory beyond which not to read files. Unlike TemplateDir, this must be a specific file path. Causes read_file to croak if
	   any filename outside of the root is provided. You should make sure that all paths specified in template_path are inside the specified
	   strict_root.  (Note that this is not a chroot jail and only affects attempts to load a file as a template; for greater security see the
	   chroot() builtin and Text::MicroMason::Safe.)

   Private Methods
       read_file
	   Intercepts file access to check for strict_root.

   EXCEPTIONS
       The following additional exceptions are generated by Text::MicroMason::TemplatePath when appropriate:

       o   Text::MicroMason::TemplatePath: template '%s' not found in path.

	   This indicates that the specified template name does not exist in any of the directories in the configured path.

       o   Text::MicroMason::TemplatePath: Template not in required base path '%s'

	   The template found in the configured template path was not within the configured strict_root directory. This may be caused by
	   requesting an absolute template filename not within strict_root, or by specifying a strict_root which does not match the configured
	   template path.

SEE ALSO

       For an overview of this templating framework, see Text::MicroMason.

       This is a mixin class intended for use with Text::MicroMason::Base.

       For distribution, installation, support, copyright and license information, see Text::MicroMason::Docs::ReadMe.

perl v5.10.1							    2009-10-27					     MicroMason::TemplatePath(3pm)