NAME

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

VERSION

version 0.2.1

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 <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 Dancer2::Template::Caribou

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