NAME

HTML::FormHandler::Manual::Reference - concise reference

VERSION

version 0.36001

DESCRIPTION

This is a concise reference of HTML::FormHandler.

HTML::FormHandler has a lot of options and many ways to customize your forms. More complete documentation can be found at HTML::FormHandler, HTML::FormHandler::Field, HTML::FormHandler::Model::DBIC, HTML::FormHandler::Render::Simple, and in the individual field classes.

Fields

Attributes for fields defined in your form:

   name          Field name. Must be the same as database column name or rel
   type          Field type. From a Field class: 'Text', 'Select', etc
   accessor      Database accessor name if different than field name
   set_validate  Name of validation method in form. Default is validate_$fieldname
   set_default   Name of the form method used to initialize a field
   required      Field is required
   order         Set the order for fields. Used by sorted_fields, templates.
   widget        Determines which rendering widget to use for the field 
   password      Remove from params and do not display in forms.
   noupdate      Don't update this field in the database
   writeonly     Do not retrieve initial values
   errors        Errors associated with this field
                 (also num_errors, clear_errors, has_errors, add_error)
   messages      Hashref of message identifiers and text
   label_column  Select lists: column to use for labels (default: name)
   active_column Select lists: which values to list
   sort_column   Select lists: column to use for sorting (default: label_column)
   size          Text & select fields.
   maxlength     Text fields. Validated.
   minlength     Text fields. Used in validation
   range_start   Range start for number fields
   range_end     Range end for number fields
   unique        Field should be unique in the database
   apply         Array of constraint/coercion/transformation actions
   value_changed Has the field's value changed from the init_value?
   dump          For debugging
   inactive, is_active, is_inactive
   input_without_param  The value of the field if there is no input from the submitted form
   default       Default value for the field
   not_nullable  Don't convert an empty field ('', etc) to undef
   trim          Transform to trim the field 
   deflation     Function to transform the field

Field Attributes for creating HTML

   html_attr   - Hashref to store arbitrary html attributes.
   label_attr  - Hashref for html attributes for the label
   wrapper_attr - Hashref for html attributes for the wrapping element (div, etc)
   label       - Text label for this field. Defaults to ucfirst field name.
   title       - Place to put title for field.
   style       - Place to put field style string
   css_class   - use wrapper_attr  { class => '..' } instead 
   input_class - use html_attr  { class => '..' } instead 
   id          - Useful for javascript (default is html_name. to prefix with
                 form name, use 'html_prefix' in your form)
   javascript  - for a Javascript string

Field attributes not set in a user form

These attributes are usually accessed in a subroutine or in a template.

   init_value    Initial value from the database
   value         The value of your field.
   input         Input value from parameter or initial value from database
   fif           Retrieve (do not set) values for filling in a form
   options       Select lists. Sorted array of hashes, keys: "value", "label"

Forms

Attributes to pass to new or set in form

   item_class    Class of db item
   item_id       Primary key of db item
   schema        Schema of item
   item          DB row object
   init_object   For default values instead of $item
   dependency    Array of arrays of field names. If one name has a value, all
                       fields in the list are set to 'required'

Other Form attributes

   name           Form name
   validated      Flag that form has validated
   ran_validation Flag that validation has already been run
   field_name_space  Where to look for your fields
   num_errors     Number of errors
   language handle  For MakeText
   params         HTTP parameters
   fields         Field array
   html_prefix    Flag to prefix html field names with the form name
   ctx            Application context for your use

Form methods

   has_field       Moose-y sugar for declaring fields
   clear           Resets state. Used in persistent forms.

   fields          The array of fields
   sorted_fields   The sorted array of fields
   field( $name )  Returns a field object
   value           Returns a hashref of values (with accessor keys)
   fif             Returns a hashref for filling in form

   has_errors      True if any field has errors
   num_errors      The number of fields with errors
   error_fields    An array of fields with errors
   errors          Returns an array of all errors
   error_field_names Returns an array of field names with errors

   uuid            Creates an HTML element 'form_uuid'

   process         Sets up form, validated, updates model
   run             Returns a result object and clears form

Form attributes useful in HTML

   html_attr - For arbitrary html attributes in the 'form' tag
   http_method - For storing 'post' or 'get'
   action - Store the form 'action' on submission. No default value.
   enctype - Request enctype
   uuid - generates a string containing an HTML field with UUID
   css_class - adds a 'class' attribute to the form tag
   style - adds a 'style' attribute to the form tag
   id/name - the form tag 'id' attribute is set to the form name

Subroutines for your form

   options_$fieldname       Provides a list of key value pairs for select lists
   validate_$fieldname      Validation routine for field
   default_$fieldname       Default value for the field in an initial form
   validate                 For validation after individual fields are validated

Methods from HTML::FormHandler::Model::DBIC for method modifiers

   validate_model    Add additional database type validation
   update_model      To perform additional database actions update

Useful in a template

   $form->has_errors    [% IF form.has_errors %]
   $field->has_errors   [% IF field.has_errors %]
   $form->error_fields  [% FOREACH field IN form.error_fields %]
   $form->error_field_names   [% FOREACH name IN form.error_field_names %]
   $form->errors        Array of error messages for all fields

   [% FOR field IN form.error_fields %]
     [% FOR error IN field.errors %]
       <p><span class='error' id=error>[% error %] </span></p>
     [% END %]
   [% END %]

   sorted_fields     [% FOREACH field IN form.sorted_fields %]
   uuid              subroutine that returns a uuid
   $form->fif        value="[% form.fif.title %]"
   $field->fif       value="[% field.fif %]

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