NAME
    Dancer::Template::TemplateFlute - Template::Flute wrapper for Dancer

VERSION
    Version 0.0099

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:

        <specification>
        <value name="content" id="content" op="hook"/>
        </specification>

    This replaces the contents of the following block in your HTML template,
    e.g. views/layouts/main.html:

        <div id="content">
        Your content
        </div>

  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"

  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;

  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
      <specification>
      <form name="registration" link="name">
      <field name="email"/>
      <field name="password"/>
      <field name="verify"/>
      </form>
      </specification>

    HTML
      <form class="frm-default" name="registration" action="/register" method="POST">
            <fieldset>
              <div class="reg-info">Info</div>
              <ul>
                    <li>
                      <label>Email</label>
                      <input type="text" name="email"/>
                    </li>
                    <li>
                      <label>Password</label>
                      <input type="text" name="password"/>
                    </li>
                    <li>
                      <label>Confirm password</label>
                      <input type="text" name="verify" />
                    </li>
                    <li>
                      <input type="submit" value="Register" class="btn-submit" />
                    </li>
              </ul>
            </fieldset>
      </form>

    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
      <specification>
      <form name="registrationtest" link="name">
      <field name="emailtest"/>
      <field name="passwordtest"/>
      <field name="verifytest"/>
      </form>
      <form name="logintest" link="name">
      <field name="emailtest_2"/>
      <field name="passwordtest_2"/>
      </form>
      </specification>

    HTML
      <h1>Register</h1>
      <form class="frm-default" name="registrationtest" action="/multiple" method="POST">
            <fieldset>
              <div class="reg-info">Info</div>
              <ul>
                    <li>
                      <label>Email</label>
                      <input type="text" name="emailtest"/>
                    </li>
                    <li>
                      <label>Password</label>
                      <input type="text" name="passwordtest"/>
                    </li>
                    <li>
                      <label>Confirm password</label>
                      <input type="text" name="verifytest" />
                    </li>
                    <li>
                      <input type="submit" name="register" value="Register" class="btn-submit" />
                    </li>
              </ul>
            </fieldset>
      </form>
      <h1>Login</h1>
      <form class="frm-default" name="logintest" action="/multiple" method="POST">
            <fieldset>
              <div class="reg-info">Info</div>
              <ul>
                    <li>
                      <label>Email</label>
                      <input type="text" name="emailtest_2"/>
                    </li>
                    <li>
                      <label>Password</label>
                      <input type="text" name="passwordtest_2"/>
                    </li>
                    <li>
                      <input type="submit" name="login" value="Login" class="btn-submit" />
                    </li>
              </ul>
            </fieldset>
      </form>

    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), <racke@linuxia.de>

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) <racke@linuxia.de>.

    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.

