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.