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
        sub {
            my $self = shift;
    
            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';
    
        sub {
            my $self = shift;
    
            html {
                head { title { 'My App' } };
                body {
                    $self->inner_template;
                };
            }
        }
    
        # in /views/hullo/bou
        
        use Template::Caribou::Tags::HTML ':all';
    
        has name => ( is => 'ro' );
    
        # in /views/howdie/inner
        sub { my $self = shift; h1 { 'hullo ' . $self->name . '!' } }

CONFIGURATION

    namespace

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

