=head1 NAME

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

=head1 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 L<HTML::FormHandler>, 
L<HTML::FormHandler::Field>, L<HTML::FormHandler::Model::CDBI>, 
L<HTML::FormHandler::Model::DBIC>, L<HTML::FormHandler::Render::Simple>,
L<Catalyst::Controller::Role::HTML::FormHandler>,
and in the individual field classes.

=head1 Fields

=head2 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
   required      Field is required
   required_message  If this field is required, the message to display on failure 
   id            Useful for javascript that requires unique id. Set in Field.
   label         Text label. Not used by FormHandler, but useful in templates 
   order         Set the order for fields. Used by sorted_fields, templates. 
   widget        Used by templates to decide widget usage. Set by field classes.
   style         Style to use for css formatting. Not used by FormHandler; for templates.
   title         For HTML titles. Not used by FormHandler.
   value_sprintf Sprintf format to use when converting input to value
   password      Remove from params and do not display in forms. 
   disabled      HTML hint to not do updates (for templates) Init: 0
   readonly      HTML hint to make the field readonly (for templates) Init: 0 
   clear         Don't validate and remove from database
   noupdate      Don't update this field in the database
   writeonly     Do not call field class's "fif_value" routine. 
   errors        Errors associated with this field 
                 (also num_errors, clear_errors, has_errors, add_error)
   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)
   sub_form      The field is made up of a sub-form (only dates at this point)
   size          Text & select fields. Validated for text.
   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 
   unique_message If field is not unique, error message.

=head2 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 (or see init_value_$fieldname) 
   value         The value of your field. Initially, init_value, then from input.
   input         Input value from parameter or initial value from database
   fif           For filling in the value in a form (from input or value)
   options       Select lists. Sorted array of hashes, keys: "value", "label"

=head2 Field subroutines to subclass in a Field class

   validate          Main part of Field subclasses. Generic validation that
                       applies to all fields of this type.
   validate_field    If you want to override the validation in a H::F::Field
   trim_value        If you don't want the default trimming 
   input_to_value    To process the field before storing, after validation
   Add your own field attributes in your custom Field classes.

=head3 Miscellaneous field subroutines
 
   set_order      Sets the field's order to the value of the form's field_counter
   has_input      Checks 'input' attribute
   fif_value      Convert the field's value to a format suitable for param hash 
   value_changed  Has the field's value changed from the init_value?
   required_text  Returns 'required' or 'optional' according to required flag
   dump           For debugging

=head1 Forms

=head2 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
   
=head2 Form Profile attributes 

   fields        Array (or hashref) of field definitions
   required      Hashref of 'required' fields
   optional      Hashref of non-required fields
   auto_required Array of required field names (types from 'guess_field_type')
   auto_optional Array of optional field names
   dependency    Array of arrays of field names. If one name has a value, all
                       fields in the list are set to 'required'

=head2 Other Form attributes

   name           Form name
   name_prefix    Flag to add/remove formname from field name in params
   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
   updated_or_created  'updated' or 'created' in database
   user_data      Place to store user data
   language handle  For MakeText 
   field_counter  For setting field order
   params         HTTP parameters 
   fields         Field array
   required       Array of required fields
   parent_field   For subforms
   active_column  The 'active' column for all select lists in the form
    
=head2 Form methods

   clear           Useful in tests
   sorted_fields
   field( $name )
   field_exists( $name )
   validate( $params )
   has_error       Ran_validation & !validated
   error_fields
   errors
   error_field_names
   uuid
   
=head2  Subroutines for your form

   options_$fieldname       Provides a list of key value pairs for select lists
   validate_$fieldname      Validation routine for field 
   init_value_$fieldname    Overrides initial value for the field
   cross_validate           For validation after individual fields are validated 
   Plus any subroutine you care to write...
   
=head2 Methods to subclass from HTML::FormHandler::Model::DBIC

   model_validate    Add additional database type validation
   update_model      To add additional actions on update
   guess_field_type  To create better field type assignment for auto forms 
     
=head1 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 %]
   
    
=head1 AUTHORS

Gerda Shank, gshank@cpan.org

=head1 COPYRIGHT

This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut

