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: 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: Similar to the Text field type, only intended for longer, multi-line strings of text.
Select: Multiple-choice field type. Provides for selecting one or more items out of a group of pre-defined options.
Toggle: Similar to the select type, but provides for only on/off state.
Number: Number field type. Contains options for defining number-specific options and limits such as decimal or integer, upper and lower bounds, etc.
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: A File selector. Used to pick a file. Works locally or as a file upload, depending on your renderer.
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

"name": The field name, used to identify this field in your program.
"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 the "Form::Simple::Field::Text" class 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.
"editable": Returns whether or not the field's value is editable.

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 flattened 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 the flattened hash structure. Should return a hashref to be merged into the flattened field hash.
"required([optional value])": Getter/setter for requiring this field for validation.

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 its own validation rules which will be performed before the "validation_delegate" is called.