NAME

Template::Provider::DBIC - Load templates using DBIx::Class

SYNOPSIS

        use My::DBIC::Schema;
        use Template;
        use Template::Provider::DBIC;

        my $schema = My::DBIC::Schema->connect(
            $dsn, $user, $password, \%options
        );
        my $resultset = $schema->resultset('Template');

If all of your templates are stored in a single table the most convenient method is to pass the provider a DBIx::Class::ResultSet.

        my $template = Template->new({
            LOAD_TEMPLATES => [
                Template::Provider::DBIC->new({
                    RESULTSET => $resultset,
                    # Other template options like COMPILE_EXT...
                }),
            ],
        });

        # Process the template 'my_template' from resultset 'Template'.
        $template->process('my_template');
        # Process the template 'other_template' from resultset 'Template'.
        $template->process('other_template');

Alternatively, where your templates are stored in several tables you can pass a DBIx::Class::Schema and specify the result set and template name in the form "ResultSet/template_name".

        my $template2 = Template->new({
            LOAD_TEMPLATES => [
                Template::Provider::DBIC->new({
                    SCHEMA => $schema,
                    # Other template options...
                }),
            ],
        });

        # Process the template 'my_template' from resultset 'Template'.
        $template->process('Template/my_template');
        # Process the template 'my_template' from resultset 'Other'.
        $template->process('Other/my_template');

In cases where both are supplied, the more specific RESULTSET will take precedence.

DESCRIPTION

Template::Provider::DBIC allows a Template object to fetch its data using DBIx::Class instead of, or in addition to, the default filesystem-based Template::Provider.

SCHEMA
This provider requires a schema containing at least the following:

• A column containing the template name. When "$template->provider($name)" is called the provider will search this column for the corresponding $name. For this reason the column must be a unique key, else an exception will be raised.
• A column containing the actual template content itself. This is what will be compiled and returned when the template is processed.
• A column containing the time the template was last modified. This must return - or be inflated to - a date string recognisable by Date::Parse.

OPTIONS
In addition to supplying a RESULTSET or SCHEMA and the standard Template::Provider options, you may set the following preferences:

COLUMN_NAME

        The table column that contains the template name. This will default
        to 'name'.

COLUMN_CONTENT

        The table column that contains the template data itself. This will
        default to 'content'.

COLUMN_MODIFIED

        The table column that contains the date that the template was last
        modified. This will default to 'modified'.

METHODS
->fetch( $name )
This method is called automatically during Template's "->process()" and returns a compiled template for the given $name, using the cache where possible.

USE WITH OTHER PROVIDERS

By default Template::Provider::DBIC will raise an exception when it cannot find the named template. When TOLERANT is set to true it will defer processing to the next provider specified in LOAD_TEMPLATES where available. For example:

        my $template = Template->new({
            LOAD_TEMPLATES => [
                Template::Provider::DBIC->new({
                    RESULTSET => $resultset,
                    TOLERANT  => 1,
                }),
                Template::Provider->new({
                    INCLUDE_PATH => $path_to_templates,
                }),
            ],
        });

CACHING

When caching is enabled, by setting COMPILE_DIR and/or COMPILE_EXT, Template::Provider::DBIC will create a directory consisting of the database DSN and table name. This should prevent conflicts with other databases and providers.

SEE ALSO

Template, Template::Provider, DBIx::Class::Schema

DIAGNOSTICS

In addition to errors raised by Template::Provider and DBIx::Class, Template::Provider::DBIC may generate the following error messages:

"A valid DBIx::Class::Schema or ::ResultSet is required"

        One of the SCHEMA or RESULTSET configuration options must be
        provided.

"%s not valid: must be of the form $table/$template"

        When using Template::Provider::DBIC with a DBIx::Class::Schema
        object, the template name passed to "->process()" must start with
        the name of the result set to search in.

"'%s' is not a valid result set for the given schema"

        Couldn't find the result set %s in the given DBIx::Class::Schema
        object.

"Could not retrieve '%s' from the result set '%s'"

        Unless TOLERANT is set to true failure to find a template with the
        given name will raise an exception.

DEPENDENCIES

• Carp
• Date::Parse
• File::Path
• File::Spec
• Template::Provider

Additionally, use of this module requires an object of the class DBIx::Class::Schema or DBIx::Class::ResultSet.

BUGS

Please report any bugs or feature requests to "bug-template-provider-dbic at rt.cpan.org", or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Provider-DBIC>.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Template::Provider::DBIC

You may also look for information at:

• Template::Provider::DBIC

  <http://perlprogrammer.co.uk/modules/Template::Provider::DBIC/>

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/Template-Provider-DBIC/>

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Provider-DBIC>

• Search CPAN

  <http://search.cpan.org/dist/Template-Provider-DBIC/>

AUTHOR

Dave Cardwell <dcardwell@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2007 Dave Cardwell. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.