README

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.