NAME
Dancer::Template::TemplateFlute - Template::Flute wrapper for Dancer
VERSION
Version 0.0113
DESCRIPTION
This class is an interface between Dancer's template engine abstraction
layer and the Template::Flute module.
In order to use this engine, use the template setting:
template: template_flute
The default template extension is ".html".
LAYOUT
Each layout needs a specification file and a template file. To embed the
content of your current view into the layout, put the following into
your specification file, e.g. views/layouts/main.xml:
This replaces the contents of the following block in your HTML template,
e.g. views/layouts/main.html:
Your content
ITERATORS
Iterators can be specified explicitly in the configuration file as
below.
engines:
template_flute:
iterators:
fruits:
class: JSON
file: fruits.json
FILTER OPTIONS
Filter options and classes can be specified in the configuration file as
below.
engines:
template_flute:
filters:
currency:
options:
int_curr_symbol: "$"
image:
class: "Flowers::Filters::Image"
ADJUSTING URIS
We automatically adjust links in the templates if the value of
`request-'path> is different from `request-'path_info>.
EMBEDDING IMAGES IN EMAILS
If you pass a value named `email_cids', which should be an empty hash
reference, all the images `src' attributes will be rewritten using the
CIDs, and the reference will be populated with an hashref, as documented
in Template::Flute
DISABLE OBJECT AUTODETECTION
Sometimes you want to pass values to a template which are objects, but
don't have an accessor, so they should be treated like hashrefs instead.
By default, the class `Dancer::Session::Abstract' is treated this way.
You can specify additional classes with the following syntax:
engines:
template_flute:
autodetect:
disable:
- My::Class1
- My::Class2
The class matching is checked by Template::Flute with `isa', so any
parent class would do.
LOCALIZATION
Templates can be localized using the Template::Flute::I18N module. You
can define a class that provides a method which takes as first (and only
argument) the string to translate, and returns the translated one. You
have to provide the class and the method. If the class is not provided,
no localization is done. If no method is specified, 'localize' will be
used. The app will crash if the class doesn't provide such method.
Be sure to return the argument verbatim if the module is not able to
translate the string.
Example configuration, assuming the class `MyApp::Lexicon' provides a
`try_to_translate' method.
engines:
template_flute:
i18n:
class: MyApp::Lexicon
method: try_to_translate
A class could be something like this:
package MyTestApp::Lexicon;
use Dancer ':syntax';
sub new {
my $class = shift;
debug "Loading up $class";
my $self = {
dictionary => {
en => {
'TRY' => 'Try',
},
it => {
'TRY' => 'Prova',
},
}
};
bless $self, $class;
}
sub dictionary {
return shift->{dictionary};
}
sub try_to_translate {
my ($self, $string) = @_;
my $lang = session('lang') || var('lang');
return $string unless $lang;
return $string unless $self->dictionary->{$lang};
my $tr = $self->dictionary->{$lang}->{$string};
defined $tr ? return $tr : return $string;
}
1;
Optionally, you can pass the options to instantiate the class in the
configuration. Like this:
engines:
template_flute:
i18n:
class: MyApp::Lexicon
method: localize
options:
append: 'X'
prepend: 'Y'
lexicon: 'path/to/po/files'
This will call
MyApp::Lexicon->new(append => 'X', prepend => 'Y', lexicon => 'path/to/po/files');
when the engine is initialized, and will call the `localize' method on
it to get the translations.
DEBUG TOOLS
If you set `check_dangling' in the engine stanza, the specification will
run a check (using the Template::Flute::Specification's `dangling'
method) against the template to see if you have elements of the
specifications which are not bound to any HTML elements.
In this case a debug message is issued (so keep in mind that with higher
logging level you are not going to see it).
Example configuration:
engines:
template_flute:
check_dangling: 1
FORMS
Dancer::Template::TemplateFlute includes a form plugin
Dancer::Plugin::Form, which supports Template::Flute forms.
The token `form' is reserved for forms. It can be a single
Dancer::Plugin::Form object or an arrayref of Dancer::Plugin::Form
objects.
Typical usage for a single form.
XML Specification
HTML
Code
any [qw/get post/] => '/register' => sub {
my $form = form('registration');
my %values = %{$form->values};
# VALIDATE, filter, etc. the values
$form->fill(\%values);
template register => {form => $form };
};
Usage example for multiple forms
Specification
HTML
Register
Login
Code
any [qw/get post/] => '/multiple' => sub {
my $login = form('logintest');
debug to_dumper({params});
if (params->{login}) {
my %vals = %{$login->values};
# VALIDATE %vals here
$login->fill(\%vals);
}
else {
# pick from session
$login->fill;
}
my $registration = form('registrationtest');
if (params->{register}) {
my %vals = %{$registration->values};
# VALIDATE %vals here
$registration->fill(\%vals);
}
else {
# pick from session
$registration->fill;
}
template multiple => { form => [ $login, $registration ] };
};
METHODS
default_tmpl_ext
Returns default template extension.
render TEMPLATE TOKENS
Renders template TEMPLATE with values from TOKENS.
SEE ALSO
Dancer, Template::Flute
AUTHOR
Stefan Hornburg (Racke),
BUGS
Please report any bugs or feature requests to `bug-template-flute at
rt.cpan.org', or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Flute.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Template::Flute
You can also look for information at:
* RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Template-TemplateFlu
te
* AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Dancer-Template-TemplateFlute
* CPAN Ratings
http://cpanratings.perl.org/d/Dancer-Template-TemplateFlute
* Search CPAN
http://search.cpan.org/dist/Dancer-Template-TemplateFlute/
LICENSE AND COPYRIGHT
Copyright 2011-2014 Stefan Hornburg (Racke) .
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.