NAME
   Dancer2::Template::Caribou - Template::Caribou wrapper for Dancer2

VERSION
   version 0.2.0

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
   "Dancer2::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 *Dancer2::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 Dancer2::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 "Dancer2::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".

CONVENIENCE ATTRIBUTES AND METHODS
   Auto-generated templates have the
   Dancer2::Template::Caribou::DancerVariables role automatically applied
   to them, which give them helper methods like "uri_for()" and "context()"
   to interact with the Dancer environment. If you roll out your own
   template classes, you simply have to apply the role to have access to
   the same niftiness.

       package Dancer2::View::MyView;

       use Moose;
       use Template::Caribou;

       with qw/
           Template::Caribou
           Dancer2::Template::Caribou::DancerVariables
       /;

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

           print ::RAW $self->uri_for( '/foo' );
       };

   context()
       The Dancer2::Core::Context object associated with the current
       request.

AUTHOR
   Yanick Champoux <[email protected]>

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.