NAME

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

VERSION

version 1.0.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

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.

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.

cpanm Dancer::Template::Caribou

perl -MCPAN -e shell
install Dancer::Template::Caribou