/ 
Form-Processor-0.20
River stage one • 4 direct dependents • 4 total dependents
/ Form::Processor::Field

NAME

Form::Processor::Field - Base class for Fields used with Form::Processor

SYNOPSIS

# Used from another class
use base 'Form::Processor::Field::Text';
my $field = Form::Processor::Field::Text->new( name => $name );

DESCRIPTION

This is a base class that allows basic functionality for form fields. Form fields inherit from this class and thus may have additional methods. See the documentation or source for the individual fields.

Look at the validate_field method for how individual fields are validated.

You are encouraged to create specific fields for your application instead of simply using the fields included with Form::Processor.

METHODS

new [parameters]

Create a new instance of a field. Any initial values may be passed in as a list of parameters.

must_submit

This boolean value defaults to false.

When true AND when the form's attribute "use_existing_values" is set then this field will not default to any existing value.

This provides a way to selectively disable "use_existing_values" on a per-field basis.

This has no effect if "use_existing_values" is false on the form.

full_name

This returns the name of the field, but if the field is a child field will prepend the field with the parent's field name. For example, if a field is "month" and the parent's field name is "birthday" then this will return "birthday.month".

form

This is a reference to the parent form object. It's stored weakened references.

sub_form

A single field can be represented by more than one sub-fields contained in a form. This is a reference to that form.

id

Returns an id for the field, which is by default:

$field->form->name . $field->id

A field may override with "init_id".

init_widget

This is the generic type of widget that could be used to generate, say, the HTML markup for the field. It's similar to the field's type(), but less specific since fields of different types often use the same widget type.

For example, a Text field would have both the type and widget values of "Text", where an Integer field would have "Integer" for the type value and "Text" as the widget value.

Normally you do not need to set this in a field class as it should pick it up from the base field class used for the specific field.

The basic types are:

Type        : Example fields
------------:-----------------------------------
text        : Text, Integer, Single field dates
checkbox    : Checkbox
radio       : Boolean (yes,no), OneToTen
select      : Select, Multiple
textarea    : HtmlArea
compound    : A field made up of other fields

Note that a Select could be a drop down list or a radio group, and that might be determined in the template code based on how many select options there are.

Multiple select fields, likewise, might be an option list or a group of checkboxes.

The default type is 'text'.

order

This is the field's order used for sorting errors and field lists.

set_order

This sets the field's order to the form's field_counter and increments the counter.

The purpose of this is when displaying fields, say in a template, this can be called with displaying the field to set its order. Then a summary of error messages can be displayed in the order the fields are on the form.

value

Sets or returns the internal value of the field.

The "validate" field method must set this value if the field validates.

required

Sets or returns the required flag on the field

errors

returns the error (or list of errors if more than one was set)

add_error

Add an error to the list of errors. If $field->form is defined then process error message as Maketext input. See $form->language_handle for details.

Returns undef. This allows:

return $field->add_error( 'bad data' ) if $bad;
max_size

This can be used to specify a max length of a field. Defaults to 10,000 characters.

Added in .20 as a sanity check.

min_length

If set "Text"-based fields must be this many charactres long to validate. Default is zero.

range_start =item range_end

Fields can have a start range and an end range. The IntRange field, for example will use this range to create a select list with a range of integers.

If one or both of range_start and range_end are set and the field does not have an options list, the field's input value will be tested to be within the range (or equal to or above/below if only one is set) by numerical comparison.

For example, in a profile:

age => {
    type            => 'Integer',
    range_start     => 18,
    range_end       => 120,
}

Will test that any age entered will be in the range of of 18 to 120, inclusive. Open ended can be done by simply:

age => {
    type            => 'Integer',
    range_start     => 18,
}
reest_errors

Resets the list of errors. The validate method clears the errors by default.

validate_field

This method does standard validation, which currently tests:

required        -- if field is required and value exists

Then if a value exists:

test_multiple   -- looks for multiple params passed in when not allowed
test_options    -- tests if the params passed in are valid options

If all of those pass then the field's validate method is called

$field->validate;

If $field->validate returns true then the input value is copied from the input attribute to the field's value attribute by calling:

$field->input_to_value;

The default method simply copies the value. This method is only called if the field does not have any errors.

The field's error list and internal value are reset upon entry.

Typically, a field may wish to override the following methods:

validate

This method should validate the input data:

$input = $field->input

The input data is the raw input provided to the form.

input_to_value

This method must copy the input data to the field's value. The default method simple does:

$field->value( $field->input );

A common use in a field would be to convert the input into an internal format. For example, converting a time or date in string form to a DateTime object.

validate_value

This method is called after converting the input data into the field's internal value. This can be used to validate the value after it's been converted. For example, for testing a DateTime object is within a given range of dates.

validate

This method validates the input data for the field and returns true if the data validates, false if otherwise. It's expected that an error message is added to the field if the field's input value does not validate.

The default method is to return true.

The method is passed the field's input value.

When overriding this method it is best to first call the parent class validate method. This way general to more specific error validation can occur. For example in a field class:

sub validate {
    my $field = shift;
    
    return unless $field->SUPER::validate;
    
    my $input = $field->input;
    #validate $input
    
    return $valid_input ? 1 : 0;
}

If the validation method produces a final value in the process of validation (e.g. creates a DateTime object from a string) then that value can either be placed in $field->value at that time and will not be copied by $field->input_to_value, or can place the value in a temporary location and then the field can also override the input_to_value method.

validate_value

This field method is called after the raw field has been validated (with the validate method) and placed in the field's value (after calling input_to_value() method).

This method can be overridden in field classes to validate a field after it's been converted into its internal form (e.g. a DateTime object).

The default method is to simply return true;

value_format

This is a sprintf format string that is used when moving the field's input data to the field's value attribute. By defult this is undefined, but can be set in fields to alter the way the input_to_value() method formates input data.

For example in a field that represents money the field could define:

sub init_value_format { '%.2f' }

And then numberic data will be formatted with two decimal places.

input_to_value

This method is called if $field->validate returns true. The default method simply copies the input attribute value to the value attribute if $field->value is undefined.

$field->value( $field->input )
    unless defined $field->value;

A field's validation method can populate a field's value during validation, or can override this method to populate the value after validation has run. Overriding this method is recommended.

test_ranges

If range_start and/or range_end is set AND the field does not have options will test that the value is within range. This is called after all other validation.

trim_value

Trims leading and trailing white space for single parameters. If the parameter is an array ref then each value is trimmed.

Pass in the value to trim and returns value back

required_message

Returns text for use in "required" message. The default is "This field is required".

test_multiple

Returns false if the field is a multiple field and the input for the field is a list.

any_input

Returns true if $self->input contains any non-blank input.

test_options

If the field has an "options" method then the input value (or values if an array ref) is tested to make sure they all are valid options.

Returns true or false

format_value

This method takes $field->value and formats it into a hash that is merged in to the final params hash. It's purpose is to take the internal value an create the key/value pairs.

By default it returns:

( $field->name, $field->value )

A Date field subclass might expaned the value into:

my $name = $field->name;
return (
    $name . 'd'  => $day,
    $name . 'm' => $month,
    $name . 'y' => $year,
);

It's up to you to not use duplicate hash values.

You might want to override test_required() if you don't use a matching field name (e.g. $name . 'd' instead of just $name).

noupdate

This boolean flag indicates a field that should not be updated. Field's flagged as noupdate are skipped when processing by the model.

This is usesful when a form contains extra fields that are not directly written to the data store.

disabled =item readonly

These allow you to give hints to how the html element is genrated. This have specific meanings in the HTML specification, but may not be consistently implemented. Disabled controls should not be successful and thus not submitted in forms, where readonly fileds can be. Instead of depending on these field attribues, an Form::Processor::Model classes should instead use the noupdate flag as an indicator if the field should be ignored or not.

clear

This is a flag that says you want to clear the database column for this field. Validation is also not run on this field.

writeonly

Fields flagged as writeonly are not fetched from the model when $form->params is called. This means the field's formatted value will not be included in the hash returned by $form->fif when first populating a form with existing values.

An example might be a situation where a trigger is used to create a copy of a row before an update. In this case you might have a required "update_reason" column that should only be written to the database on updates.

Unlike the password flag, this only prevents populating a field from the field's initial value, but not from the parameter hash passed to the form. Redrawn forms (after validation failures) will display the value submitted in the form.

password

This is a boolean flag and if set the $form->params method will remove that field when calling $form->fif.

This is different than the writeonly method above in that the value is removed from the hash every time its fetched.

value_changed

Returns true if the value in the item has changed from what is currently in the field's value.

This only does a string compare (arrays are sorted and joined).

required_text

Returns "required" or "optional" based on the field's setting.

has_error

Returns the count of errors on the field.

dump_field

A little debugging.

AUTHOR

Bill Moseley - with *much* help from John Siracusa. Most of this is based on Rose-HTML-Form. It's basically a very trimmed down version without all the HTML generation and the ability to do compound fields.