/ 
HTML-FormHandler-0.20
River stage two • 21 direct dependents • 31 total dependents
/ HTML::FormHandler::Manual::Reference

NAME

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

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
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.
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.
apply         Array of constraint/coercion/transformation actions

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           Retrieve (do not set) values for filling in a form 
options       Select lists. Sorted array of hashes, keys: "value", "label"

Field subroutines to subclass in a Field class

validate          Main part of Field subclasses. Generic validation that
                    applies to all fields of this type.
Add your own field attributes in your custom Field classes.

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

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'

Form field_list 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

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
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         For compound/related fields: parent field reference 
active_column  The 'active' column for all select lists in the form
html_prefix    Flag to prefix html field names with the form name
submit
http_method
action
user_data
ctx

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( $name )  Returns the value for a field object
 field_exists( $name ) Returns a field object if it exists, otherwise undef
 values          Returns a hashref of values (with accessor keys)
 fif             Returns a hashref for filling in form  

 has_error       Ran_validation & !validated
 has_errors      True if any field has errors 
 num_errors      The number of fields with errors
 error_fields    Returns 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         Does 'clear' and 'update' for persistent forms
 update          Sets up form, validates form, updates model
 validate        For non-db forms: sets up, clears, validates
 validate_form   Validates form

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...

Methods to subclass from HTML::FormHandler::Model::DBIC

validate_model    Add additional database type validation
update_model      To perform additional database actions update
guess_field_type  To create better field type assignment for auto forms

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 %]

AUTHORS

Gerda Shank, gshank@cpan.org

COPYRIGHT

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