NAME

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

VERSION
version 0.1.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".

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.