=head1 NAME

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

=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 
   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 Other form settings

   dependency    Array of arrays of field names. If one name has a value, all
                       fields in the list are set to 'required'

=head2 Attributes and Subroutines for your form

   item_class               Specifies the class of your model object 
   schema                   If you're not using the schema from a Catalyst model
   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 
   active_column            For all select lists in the form
   init_object              Provide different but similar object to init form 
                               such as default values (field names must match)
   field_counter            Increment in templates 
   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 
     
=head2 Particularly useful in a template

   $form->has_errors    [% IF form.has_errors %]
   $field->has_errors   [% IF field.has_errors %] 
   error_fields         [% FOREACH field IN form.error_fields %]
   error_field_names    [% FOREACH name IN form.error_field_names %]

   [% 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 %]
   
=head2 L<HTML::FormHandler::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.
    
=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

