This can be used to specify the location or locations of templates. In the simple case it can be specified as a single string denoting a file system location.

my $templates = Template::TT3::Templates->new(
    template_path => '/path/to/templates',
);

Multiple locations can be specified using an array reference.

my $templates = Template::TT3::Templates->new(
    template_path => [
        '/path/to/my/templates',
        '/path/to/your/templates',
    ],
);

The template_path option can also be specified using the shorter alias path.

This can be used to define the default dialect for templates. The default dialect is TT3 if not otherwise specified. You can set it to any module or short name that is recognised by the Template::TT3::Dialects factory module. For example, if you want to use the TT2 dialect you would write:

my $templates = Template::TT3::Templates->new(
    dialect => 'TT2',
);

Note that this only specifies the default dialect. This may be over-ridden by a different dialect setting in the template_path

my $templates = Template::TT3::Templates->new(
    dialect       => 'TT2',
    template_path => [
        { path    => '/path/to/my/templates' },     # uses TT2 dialect
        { path    => '/path/to/your/templates',     # uses TT3 dialect
          dialect => 'TT3' 
        }
    ],
);

This can be used to provide an object suitable for caching compiled templates. The default caching module is Template::TT3::Cache but you can substitute any Cache::Cache module to work in its place.

This can be used to provide an object suitable for storing compiled templates to disk or some other secondary storage medium. The default store module is Template::TT3::Store but you can substitute any Cache::Cache module to work in its place.

NOTE: The store isn't working as we don't yet have a view to generate Perl code from compiled templates. This needs some work.

The Template::TT3::Templates module performs some additional internal caching to quickly map template paths to cached templates without going through the rigamarole of check each location every time. However, if your template_path can change from one request to the next then there is no guarantee that the hello.tt3 template we fetched last time you asked for it is going to be the same hello.tt3 template that you get this time.

The dynamic_path option can be set to any true value to indicate that the template_path can change at any time. This will bypass the fast path lookup and ensure that the template_path providers are queried each time.

This option is used in conjunction with the lookup path cache described above in dynamic_path . Even with a static template_path there is still the possibility that the templates on disk can change. We want to avoid doing the full filesystem check for every request so we cache template paths for a short while (typically a few seconds) before checking again. The path_expires option can be set to indicate how much time should elapse (in seconds) before a full filesystem check is performed.

If your templates never change or change infrequently then you can set this to an arbitrarily large number (e.g. 3600 to check one every hour). If you're a developer using a persistent template processing environment (e.g. a mod_perl handler) and you're changing your templates often then you should set this to a small number (e.g. 1 second) so that you can reload your browser and see any changes straight away.

In the usual case the template_path is used internally to generate a list of provider object responsible for locating and loading templates. The template_providers option can be specified to override this. This is an advanced option and you are expected to know what you are doing if you use it.

This method locates loads and returns a template object.

If the first argument is a reference of any kind then the method delegates to the template_ref() method.

$templates->template($ref);         # calling this...
$templates->template_ref($ref);     # ...ends up calling this

If a single non-reference argument is specified then the method delegates to the template_name() method.

$templates->template('foo');        # calling this...
$templates->template_name('foo');   # ...ends up calling this

If more than one argument is specified then the method delegates to the template_type() method.

$templates->template(               # calling this...
    text => 'Hello [% name %]' 
);
$templates->template_type(          # ...end up calling this
    text => 'Hello [% name %]'
)

All arguments passed to the template() method are forwarded to the appropriate delegate method. The template() method returns whatever value its delegate method returns.

If the template cannot be found then the method returns undef. A message indicating why it declined can be retrieved via the reason() method (inherited from Badger::Base ).

my $template = $templates->fetch('missing.tt3')
    || die $templates->reason;          # Template not found: missing.tt3

All errors are thrown as exceptions. For example, if the module find a file but cannot open it, or if a template is found but it contains a syntax error, then an exception will be raised.

Failing to find a template that was requested is not considered to be an error condition. Rather, it is part and parcel of correct operation for the module. You ask if a template is available and the module replies "Yes, here it is" (a template object is returned) or "No, it isn't" (undef is returned).

This method returns a template object for the reference passed as the first argument, $ref. It can be any of the following types:

A template can be specified by reference to an array containing further arguments that specify the type and/or name of a template.

$templates->template_ref([ file => 'example.tt3' ]);
$templates->template_ref([ text => 'Hello [% name %]' ]);

In this case the method delegates back to the template() method, expanding the contents of the array onto the start of the parameter list.

A template can be specified by reference to a hash array. If this contains exactly one key/value pair then it is treated as a template type and identifier (e.g. file name, template text, etc).

$templates->template_ref({ file => 'example.tt3' });
$templates->template_ref({ text => 'Hello [% name %]' });

In this case the method delegates back to the template() method, adding the type (key) and identifier (value) to the start of the parameter list.

If the hash array contains more than one key/value pair then it is treated as a complete parameter specification for a template and is forwarded to the lookup() method.

A template can be specified by reference to a subroutine that generates the template output. This is delegated to the template_code() method.

A template can be specified by reference to a Perl GLOB (e.g. \*STDIN, \*DATA) from which the template source can be read. This is delegated to the template_glob() method.

A template can be specified by reference to an IO::Handle object (or subclass) defining a file handle from which the template source can be read. This is delegated to the template_handle() method.

This method prepares a template object from a code reference which implements the output generating logic for a template.

my $code = sub {
    my $context = shift;
    return "Hello " . $context->var('name')->value;
}

my $template = $templates->template_code($code);

print $template->fill( name => 'World' );       # Hello World

This method prepares a template object from a Perl GLOB reference (e.g. \*STDIN, \*DATA) from which the template source can be read.

my $template = $templates->template_glob(\*DATA);

print $template->fill( name => 'World' );       # Hello World

__DATA__
Hello [% name %]

This method prepares a template object from an IO::Handle object (or subclass) from which the template source can be read.

use Badger::Filesystem 'File';

my $filehandle = File('hello.tt3')->open;
my $template   = $templates->template_handle($filehandle);

print $template->fill( name => 'World' );       # Hello World

This method prepares a template object from a text string or reference to a text string.

my $source   = 'Hello [% name %]';
my $template = $templates->template_text($source);   # either
my $template = $templates->template_text(\$source);  # or

print $template->fill( name => 'World' );       # Hello World

This method prepares a template object from the name passed as an argument. It looks through all locations in the template_path until it finds a template matching the $name specified. It returns a template object or undef if the template cannot be found.

my $template = $templates->template_name('hello.tt3')
    || die $templates->reason;      # e.g. Template not found: hello.tt3

print $template->fill( name => 'World' );       # Hello World

This method prepares a template object using the $type and $name passed as arguments. If $type is text, code, glob, handle or fh (an alias for handle) then it delegates to template_text() , template_code() , template_glob() or template_handle() , respectively.

$template = $templates->template_type( text   => 'Hello [% name %]' );
$template = $templates->template_type( code   => sub { ... } );
$template = $templates->template_type( glob   => \*STDIN );
$template = $templates->template_type( handle => $fh );
$template = $templates->template_type( fh     => $fh );

Otherwise it queries each of the providers for the template_path that correspond to the specified $type. In the usual case the type will be file and all filesystem-based providers will respond.

my $template = $templates->template_type( file => 'hello.tt3' )
    || die $templates->reason;      # e.g. Template not found: hello.tt3

print $template->fill( name => 'World' );       # Hello World

Initialisation method. In turn this calls init_path() and init_providers() .

Initialisation method used to prepare the template_path .

Initialisation method used to create a template provider for each location in the template_path . Template providers are implemented as subclasses of Template::TT3::Provider . In the usual case these will be Template::TT3::Provider::File objects for fetching templates from the file system.

Provider objects are loaded and instantiated by the Template::TT3::Providers factory module.

This method is used internally by the template() method and friends. It accepts a list or reference to a hash array of named parameters that define initialisation parameters for a template. If an id parameter is specified then the method will call cache_fetch() to see if a cached version of the compiled template is available. Otherwise it will call the prepare() method to prepare it.

This method is used internally by the template_type() method. It queries the provider for each location in the template_path to see if it can provide the requested template. If the type parameter is defined then it will only queries those providers corresponding to that type.

This method checks to see if a cached version of a template is available. The cache is implemented using a Template::TT3::Cache object. The Template::TT3::Store module may also be used to provide persistent secondary storage for compiled templates. However this is not operational at the time of writing because we don't yet have the appropriate view to convert compiled templates to Perl code.

The method returns a template object from the cache or undef if none is available.

This method is used to store a compiled template in the in-memory cache and/or secondary store.

This method is used to prepare a new template object from a set of configuration parameters.

This method is called after a new template object is prepared by the prepare() method. It takes care of updating the cache (via a call to cache_store() ) and updating the internal path lookup table for optimising subsequent requests for the same template.

This method creates a unique (for practical purposes) identifier from a text string. It is comprised of the text: prefix followed by an MD5 hash of the text.

This method creates a unique (for practical purposes) identifier from a code references. It is comprised of the code: prefix followed by the memory address of the code reference.

This method is used to report templates that cannot be found. It creates a decline message and returns undef. The message can be retrieved via a call to the reason() method inherited from Badger::Base .

my $template = $templates->template('missing.tt3')
    || die $templates->reason;

This method constructs a default template_path for those times when is hasn't been explicitly defined. The default path contains a single Template::TT3::Provider::Cwd provider object which serves templates from the current working directory of the filesystem.

This method is used to explicitly cleanup the providers it is using at garbage collection time.

This method is used to explicitly cleanup the object at garbage collection time.

This is a lookup table mapping text, code, glob, handle and fh (an alias for handle) to the template_text() , template_code() , template_glob() and template_handle() methods respectively.