NAME

Form::Sensible::Field - Field base class for Form::Sensible

SYNOPSIS

use Form::Sensible::Field;

my $field = Form::Sensible::Field->create_from_flattened( { 
    field_class => 'Text',
    name => 'username',
    validation => {  regex => '^[0-9a-z]*$'  }
 } );

$field->value('bob');

my $saveforlater = $field->flatten();

DESCRIPTION

Form::Sensible::Field provides the basic functionality for all field types in Form::Sensible. All form field classes indended for use with Form::Sensible should extend Form::Sensible::Field. Form::Sensible is distributed with the following field classes:

Text: Form::Sensible::Field::Text

Simple text field, for storage of simple strings of text. Defaults to a maximum length of 256. If you are looking for multi-line text, it's probably better to use the LongText type.

LongText: Form::Sensible::Field::LongText

Similar to the Text field type, only intended for longer, multi-line strings of text.

Select: Form::Sensible::Field::Select

Multiple-choice field type. Provides for selecting one or more items out of a group of pre-defined options.

Toggle: Form::Sensible::Field::Toggle

Similar to the select type, but provides for only on/off state.

Number: Form::Sensible::Field::Number

Number field type. Contains options for defining number-specific options and limits such as decimal or integer, upper and lower bounds, etc.

Trigger: Form::Sensible::Field::Trigger

A Trigger. Causes something to happen, most often form validation and processing. Trigger fields are most often rendered as buttons in graphical interfaces.

FileSelector: Form::Sensible::Field::FileSelector

A File selector. Used to pick a file. Works locally or as a file upload, depending on your renderer.

SubForm: Form::Sensible::Field::SubForm

A field type that allows you to include an entire other form into the current form. Useful for creating blocks of fields which can be included into other forms easily.

We believe that almost all form based values can fit into these types. Keep in mind that these are not intended to represent all presentations of form data. Select fields, for example could be rendered as a dropdown select-box or as a group of checkboxes, depending on the renderer selected and the render_hints provided.

If you feel we've missed something, please drop us a line, or drop by #form-sensible on irc.perl.org.

ATTRIBUTES

display_name The name used when displaying messages about this field, such as errors, etc. Defaults to uc($field-name)>.

field_type A string identifying this type of field. Normally defaults to the last portion of the classname, for example, for a Form::Simple::Field::Text the field_type would be 'text'

validation Hashref containing information used in validation of this field. The content of the hashref depends on the validator being used. If the built-in Form::Sensible::Validator is being used, the three keys that may be present are required, regex and code. The required element should contain a true/false value indicating whether the field must be present for validation to pass. The regex element should contain either a regex pattern or a regex reference to be applied to the field. The code element should contain an code reference used to validate the field's value. For more information, see Form::Sensible::Validator.

render_hints Hashref containing hints to help the renderer render this field. The hints available depend on the renderer being used.

value The current value for this field.

accepts_multiple Can the field support multiple values. Defaults to false. If an array of values is passed as the value on a field that doesn't accept multiple values, only the first value will be used, the remainder will be ignored.

default_value The default value to use if none is provided.

METHODS

validate()

Validation specific to the field. This is usually used to provide validation that only applies to the given type of field, for example, ensuring that the value provided matches the available options in a select box.

clear_state()

Clears the state for this field. In most cases simply clears out the value field, but may do additional state-cleaning work on complex fields. Note that if you subclass the Field class and then provide a custom value() routine or attribute, you _MUST_ also override clear_state in your subclass.

create_from_flattened()

Creates a new field object using the provided flattenned field information. Note that this will use the field_class element in the provided hash to determine the appropriate object type to create.

flatten([$template_only])

Flattens the current field into a non-blessed hashref that can be used to recreate the field later. If $template_only is provided and is true, only the data required to re-create the field is provided, and no additional state (such as the current value) is returned.

get_additional_configuration()

Helper function to flatten(), used by subclasses to add additional information specific to the subclass type into in the flattened hash structure. Should return a hashref to be merged into the flattened field hash.

DELEGATES

value_delegate->($self, [optional value])

The value_delegate is called to get or set the value for this field. The first argument is the Field object itself, which will be the only parameter if it is called as a getter. If called as a setter, an additional value argument will be passed. In both scenarios, the delegate should return the field's (new) value.

validation_delegate->($self, $value)

The validation_delegate is called to validate the value given for the field. As with all delegates, the first argument is the field itself, the second argument is the value to be validated. The delegate is expected to return an arrayref containing error messages if invalid, or false (scalar) if valid. It may be help to think of it as the field asking the delegate 'is this invalid.'

Note that each field type may have it's own validation rules which will be performed before the validation_delegate is called.

AUTHOR

Jay Kuri - <jayk@cpan.org>

SPONSORED BY

Ionzero LLC. http://ionzero.com/

SEE ALSO

Form::Sensible

LICENSE

Copyright 2009 by Jay Kuri <jayk@cpan.org>

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