NAME

HTML::FormHandler::Manual::Templates - using templates

VERSION

version 0.36003

SYNOPSIS

Documentation on templates to use with HTML::FormHandler

Using templates

There is a FormHandler Template Toolkit rendering role at HTML::FormHandler::Render::WithTT, with a testcase in t/render_withtt.t. Normally, however, it probably won't make much sense to use both a TT parser in FormHandler, and a separate one for the "complete" templates, so it seems like the TT renderer would mainly be useful for tests, or as an example of how to do TT rendering with HFH.

There are lots of different ways to set up templates. There are sample templates installed in FormHandler's 'share' directory. These templates are now organized more-or-less similarly to the widget roles, with 'field', 'wrapper', and 'form' directories, but many other organizations are possible.

Another organization would be to store all template snippets in a 'widget' directory.

You can use the default 'widget' for the field class, or set the 'widget' for the field in your form:

   fields => [
      my_special_field => {
         type => 'Text',
         widget => 'my_special_widget',
      },
      my_second_field => {
         type => 'Text',
         widget => 'yet_another_widget',
      },
   ]

And include them in a generic template:

   [% PROCESS widget/form_start.tt %]

   [% FOREACH f IN form.sorted_fields %]
      [% PROCESS widget/${f.widget}.tt %]
   [% END %]

   [% PROCESS widget/form_end.tt %]

Field attributes

If you want to use the 'process_attrs' function to pull in HTML attributes for the input elements, wrappers, and labels, you would need to pass that function into your TT setup. See HTML::FormHandler::Render::WithTT for an example:

    use HTML::FormHandler::Render::Util ('process_attrs');
    $c->stash( process_attrs => &process_attrs ); # or add to TT vars in your view

    label [% process_attrs(f.label_attributes) %]for="[% f.html_name %]">
    [% f.label %]: </label>
    <input type="[% f.input_type %]" name="[% f.html_name %]" id="[% f.id %]" 
    [% process_attrs(f.attributes) %] value="[% f.fif %]">

Sample templates

Note that the following templates assume that the field is in a TT variable "f", as though they were processed in the above loop. Otherwise the individual fields could be preceded by something like:

  [% f = form.field('title') %]

Text input field with error class on div & error messages

   <div class="[% f.css_class %] [% IF f.has_errors %]error_fld[% END %]">
   [% IF f.has_errors %]
     [% FOR error IN f.errors %]
       <p><span class="error" id="error">[% error %] </span></p>
     [% END %]
   [% END %]
   <label class="label" for="[% f.id %]">[% f.label %]</label>
   <input type="text" name="[% f.html_name %]" id="[% f.id %]" value="[% f.fif %]">
   </div>

Simple text field;

   [% f = form.field('text_field') %]
   <div><label class="label" for="[% f.id %]">[% f.label %]: </label>
   <input type="text" name="[% f.html_name %]" id="[% f.id %]" value="[% f.fif %]" /> </div>

Select field

Single select:

   <label class="label" for="[% f.id %]">[% f.label %]</label>
   <select name="[% f.html_name %]" id="[% f.id %]>
     [% FOR option IN f.options %]
       <option value="[% option.value %]"
       [% IF option.value == f.fif %]
          selected="selected"
       [% END %]>
       [% option.label %]</option>
     [% END %]
   </select>

Multiple select:

   <label class="label" for="[% f.id %]">[% f.label %]</label>
   <select name="[% f.html_name %]" id="[% f.id %]
             multiple="multiple" size="[% f.size %]">
     [% FOR option IN f.options %]
       <option value="[% option.value %]"
       [% FOREACH optval IN f.value %]
          [% IF optval == option.value %]
             selected="selected"
          [% END %]
       [% END %]>
       [% option.label %]</option>
     [% END %]
   </select>

Warning: TT has problems with single element arrays. If you are likely to have a single element in a select list, you might want to use the rendering method instead or add an extra "choose" row. (If you come up with a good solution, please submit a doc patch.)

Checkbox

   <div><label class="label" for="[% f.id %]">[% f.label %]: </label>
   <input type="checkbox" name="[% f.html_name %]" id="[% f.id %]" value="1" />
   </div>

Textarea

   <div><label class="label" for="[% f.id %]">[% f.label %]: </label>
   <textarea name="[% f.html_name %]" id="[% f.id %]"
        rows="[% f.rows %]" cols="[% f.cols %]">[% f.fif %]</textarea></div>

Hidden

   <div><input type="hidden" name="[% f.html_name %]" id="[% f.id %]"
       value="[% f.fif %]" /></div>

Submit

   <div><input type="submit" name="[% f.html_name %]" id="[% f.id %]"
       value="[% f.value %]" /></div>

Radio group

   <div>
   <label class="label" for="[% f.id %]">[% f.label %]</label>
   [% FOR option IN f.options %]
     <input type="radio" value="[% option.value %]"
        name="[% f.name %]"
     [% IF option.value == f.fif %]
        checked="checked"
     [% END %]>
     [% option.label %]<br />
   [% END %]
   </div>

AUTHOR

FormHandler Contributors - see HTML::FormHandler

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Gerda Shank.

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 HTML::FormHandler

perl -MCPAN -e shell
install HTML::FormHandler