The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Form-Diva-0.0501-TRIAL
River stage one • 1 direct dependent • 1 total dependent
/ Form::Diva

NAME

Form::Diva - Generate HTML5 form label and input fields

VERSION

version 0.0501

SYNOPSIS

Generate Form Label and Input Tags from a simple data structure. Simplify form code in your views without replacing it without a lot of even uglier Perl Code in your Controller.

Drastically reduce form clutter in your View Templates with small Data Structures.

DESCRIPTION

Create a new instance of Form::Diva from an array_ref of hash_refs describing each field of your form. The most common attributes have a single letter abbreviation to reduce typing.

Return a similar structure of the label and input attributes ready for inclusion in a web page by your templating system.

USAGE

 use Form::Diva;

 my $diva = Form::Diva->new(
    label_class => 'col-sm-3 control-label',
    input_class => 'form-control',
    form        => [
        { n => 'name', t => 'text', p => 'Your Name', l => 'Full Name' },
        { name => 'phone', type => 'tel', extra => 'required' },
        { qw / n email t email l Email c form-email placeholder doormat/},
        { name => 'myradio', type => 'radio', default => 1,
           values => [ "1:Yes", "2:No", "3:Maybe" ] },   
    ],
 );

 my $fields = $diva->generate;
 my $filledfields = $diva->generate( $hashref_of_data );

Once you send this to your stash or directly to the templating system the form might look like:

  <form class="form-horizontal well col-md-8" role="form"
   method="post" action="/form1" name="DIVA1" >  

  <div class="form-group">
In Template Toolkit:
  [% FOREACH field IN fields %] {
    [% field.label %]
    <div class="col-sm-8">
        [% field.input %]
    </div>
  [% END %]
Or in Mojo::Template
  % foreach my $field (@$fields) {
    <%== $field->{'label'} %>
    <div class="col-sm-8">
        <%== $field->{'input'} %>
    </div>
 % }

 </div>

 <div class="form-group">
    <div class="col-sm-offset-3 col-sm-8">
      <input type="submit" class="btn btn-large btn-primary" 
      name="submit" value="submit_me" >&nbsp;
    </div>
 </div>
 </form>

METHODS

new

Create a new object from a Data Structure ().

generate

When called without arguments returns the blank form with placeholders and value set to default or null if there is no default.

When provided an optional hashref of data it sets values based on the hashref and suppresses placeholder.

The data returned is in the form of an array reference with a hash reference for the label and input attributes.

A second optional hashref may be passed to override the values list for select, checkbox and radio button inputs, see below.

clone

Copy a Form::Diva object optionally modifiying some of the values in the copy. This is useful if you have several similar forms, define a form diva object with all of the fields, then make copies for the shorter forms.

 my $newdiva = $diva->clone({ 
    neworder => [ qw / A B c D E /], });

Arguments to clone

Arguments to clone are passed as a hashref. All of the arguments are optional since if omitted the value of the original object is just copied. clone with no arguments would just make a copy of your original object. The arguments are:

neworder

An array ref of the names of the fields in your form. This will let you re-order fields and you do not need to include all of the fields. You cannot define new fields on a clone but you can omit them.

input_class, label_class

Change these values for your copy.

The Form::Diva Data Structure

 { label_class => 'some class in your css',
   input_class => 'some class in your css',
   form        => [
        { name => 'some_field_name', ... },
        ...
   ],
 }

label_class, input_class

Specify the contents the label's class attribute and the input's class attribute. The input_class can be over-ridden for a single field by using the c/class attribute in a field definition.

If you need to access these two values they both have accessor methods $diva->label_class() and $diva->input_class();.

form

Form::Diva knows about the most frequently needed attributes in HTML5 label and input tags. The attribute extra is provided to handle valueless attributes like required and attributes that are not explicitly supported by Form::Diva. Each supported tag has a single character shortcut. When no values in a field definition require spaces the shortcuts make it extremely compact to describe a field using qw/.

The only required value in a field definition is name. When not specified type defaults to text.

Multivalued fields are not currently supported, but may be in the future.

Supported attributes and their shortcuts

 c       class        over-ride input_class for this field
 d       default      sets value for an empty form
 e,x     extra        any other attribute(s)
 i       id           defaults to name
 l       label        defaults to ucfirst(name)
 n       name         field name -- required
 p       placeholder  placeholder to show in an empty form
 t       type         checkbox, radio, textarea or any input types
                      type defaults to text input type
 v       values       for radio and checkbox inputs only

extra attribute

The contents of extra are placed verbatim in the input tag. Use for HTML5 attributes that have no value such as disabled and any of the other attributes you may wish to use in your forms that have not been implemented, you will need to type out attribute="something" if it is not valueluess.

Common Attributes with no Value

disabled, readonly, required

Should be placed in the extra field when needed.

TextArea

TextArea fields are handled the same as the text type.

Select Radio Button and CheckBox

Select, Radio Button and CheckBox Input types are similar to each other, and take an extra attribute 'values'. Form::Diva does not currently support multi-valued CheckBoxes, if a record's data has multiple values only one will be selected in the form.

values

For CheckBoxes the values attribute is just the values of the check boxes. If value is set and matches one of the values it will be checked.

  { type => 'checkbox',
    name => 'mycheckbox',
    values => [ 'Miami', 'Chicago', 'London', 'Paris' ] }

For RadioButtons the values attribute is a number and text seperated by a colon. When the form is submitted just the number will be returned.

  { t => 'radio',
    n => 'myradio',
    v => [ '1:New York', '2:Philadelphia', '3:Boston' ] }

For Select inputs there are two forms of values. If the value itself and the label are the same then values is just a list of those values which will also be used as the label. The second form requires the value and the label to be seperated by a colon.

  values => [ qw /pineapple persimmon nectarine ]
  or 
  values => [ 'item1:Pineapple', 'item2:Georgia Peach', 'item3:Naval Orange']

When using the first form of values the label is not CamelCased or otherwise changed, if you want that you'll need to use the second form.

Over-Riding Values

It is possible to override values by passing an extra argument to generate. The override argument is a hashref { field_name => [ values ...]}. It is even possible to create your initial object with an empty values lists and pass a list every time you generate the form.

AUTHOR

John Karr, brainbuz at brainbuz.org

BUGS

Please report any bugs or feature requests through the web interface at https://bitbucket.org/brainbuz/formdiva/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Form::Diva

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2014 John Karr.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.