NAME
    Dancer::Template::Caribou - Template::Caribou wrapper for Dancer

VERSION
    version 0.1.1

SYNOPSIS
        # in 'config.yml'
        template: Caribou

        engines:
          template:
            Caribou:
              namespace:    MyApp::View
              auto_reload:  1


        # and then in the application
        get '/' => sub { 
            ...;

            template 'main' => \%options;
        };

DESCRIPTION
    "Dancer::Template::Caribou" is an interface for the Template::Caribou
    template system. Be forewarned, both this module and "Template::Caribou"
    itself are alpha-quality software and are still subject to any changes.
    <Caveat Maxima Emptor>.

  Basic Usage
    At the base, if you do

        get '/' => sub {
            ...

            return template 'MyView', \%options;
        };

    the template name (here *MyView*) will be concatenated with the
    configured view namespace (which defaults to *Dancer::View*) to generate
    the Caribou class name. A Caribou object is created using %options as
    its arguments, and its inner template "page" is then rendered. In other
    words, the last line of the code above becomes equivalent to

        return Dancer::View::MyView->new( %options )->render('page');

  '/views' template classes
    Template classes can be created straight from the "/views" directory.
    Any directory containing a file named "bou" will be turned into a
    "Template::Caribou" class. Additionally, any file with a ".bou"
    extension contained within that directory will be turned into a inner
    template for that class.

   The 'bou' file
    The 'bou' file holds the custom bits of the Template::Caribou class.

    For example, a basic welcome template could be:

        # in /views/welcome/bou
    
        use Template::Caribou::Tags::HTML ':all';

        has name => ( is => 'ro' );

        template page => sub {
            my $self = shift;

            html {
                head { title { 'My App' } };
                body {
                    h1 { 'hello ' . $self->name .'!' };
                };
            }
        };

    which would be invoqued via

        get '/hi/:name' => sub {
            template 'welcome' => { name => param('name') };
        };

   The inner template files
    All files with a '.bou' extension found in the same directory as the
    'bou' file become inner templates for the class. So, to continue with
    the example above, we could change it into

        # in /views/howdie/bou
    
        use Template::Caribou::Tags::HTML ':all';

        has name => ( is => 'ro' );


        # in /views/howdie/page
        html {
            head { title { 'My App' } };
            body {
                h1 { 'howdie ' . $self->name . '!' };
            };
        }

   Layouts as roles
    For the layout sub-directory, an additional piece of magic is performed.
    The 'bou'-marked directories are turned into roles instead of classes,
    which will be applied to the template class. Again, to take our example:

        # in /views/layouts/main/bou
        # empty file

        # in /views/layouts/main/page
    
        # the import of tags really needs to be here 
        # instead than in the 'bou' file 
        use Template::Caribou::Tags::HTML ':all';

        html {
            head { title { 'My App' } };
            body {
                show( 'inner' );
            };
        }

        # in /views/hullo/bou
    
        use Template::Caribou::Tags::HTML ':all';

        has name => ( is => 'ro' );

        # in /views/howdie/inner
        h1 { 'hullo ' . $self->name . '!' };

CONFIGURATION
    namespace
        The namespace under which the Caribou classes are created. defaults
        to "Dancer::View".

    auto_reload
        If set to "true", the Caribou object will verify if any of the
        template files have changed before rendering and, if that's the
        case, will self-update. Defaults to "false".

AUTHOR
    Yanick Champoux <yanick@babyl.dyndns.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Yanick Champoux.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.