/ 
Rose-HTML-Objects-0.0131
River stage two • 10 direct dependents • 12 total dependents
/ Rose::HTML::Form::Field

NAME

Rose::HTML::Form::Field - HTML form field base class.

SYNOPSIS

package MyField;

use Rose::HTML::Form::Field;
our @ISA = qw(Rose::HTML::Form::Field);
...

my $f = MyField->new(name => 'test', label => 'Test');

print $f->html_field;
print $f->xhtml_field;

$f->input_value('hello world');

$i = $f->internal_value;

print $f->output_value;
...

DESCRIPTION

Rose::HTML::Form::Field is the base class for field objects used in an HTML form. It defines a generic interface for field input, output, validation, and filtering.

This class inherits from, and follows the conventions of, Rose::HTML::Object. Inherited methods that are not overridden will not be documented a second time here. See the Rose::HTML::Object documentation for more information.

OVERVIEW

A field object provides an interface for a logical field in an HTML form. Although it may serialize to multiple HTML tags, the field object itself is a single, logical entity.

Rose::HTML::Form::Field is the base class for field objects. Since the field object will eventually be asked to serialize itself as HTML, Rose::HTML::Form::Field inherits from Rose::HTML::Object. That defines a lot of a field object's interface, leaving only the field-specific functions to Rose::HTML::Form::Field itself.

The most important function of a field object is to accept and return user input. Rose::HTML::Form::Field defines a data flow for field values with several different hooks and callbacks along the way:

               +------------+
              / user input /
             +------------+
                    |
                    V
           +------------------+
    set -->.                  .
           .   input_value    .   input_value()
    get <--.                  .
           +------------------+
                    |
                    V
           +------------------+
 toggle -->| input_prefilter  |   trim_spaces()
           +------------------+
                    |
                    V
           +------------------+
define <-->|   input_filter   |   input_filter()
           +------------------+
                    |
                    V
         +----------------------+
         .                      .
  get <--. input_value_filtered . input_value_filtered()
         .                      .
         +----------------------+
                    |
                    V
           +------------------+
           |   inflate_value  |   (override in subclass)
           +------------------+
                    |
                    V
           +------------------+
           .                  .
    get <--.  internal_value  .   internal_value()
           .                  .
           +------------------+                      
                    |
                    V
           +------------------+
           |   deflate_value  |   (override in subclass)
           +------------------+
                    |
                    V
           +------------------+
define <-->|   output_filter  |   output_filter()
           +------------------+
                    |
                    V
           +------------------+
           .                  .
    get <--.   output_value   .   output_value()
           .                  .
           +------------------+

Input must be done "at the top", by calling input_value(). The value as it exists at various stages of the flow can be retrieved, but it can only be set at the top. Input and output filters can be defined, but none exist by default.

The purposes of the various stages of the data flow are as follows:

input value

The value as it was passed to the field.

input value filtered

The input value after being passed through all input filters, but before being inflated.

internal value

The most useful representation of the value as far as the user of the Rose::HTML::Form::Field-derived class is concerned. It has been filtered and optionally "inflated" into a richer representation (i.e., an object). The internal value must also be a valid input value.

output value

The value as it will be used in the serialized HTML representation of the field, as well as in the equivalent URI query string. This is the internal value after being optionally "deflated" and then passed through an output filter. This value should be a string or a reference to an arry of strings. If passed back into the field as the input value, it should result in the same output value.

Only subclasses can define class-wide "inflate" and "deflate" methods (by overriding the no-op implementations in this class), but users can define input and output filters on a per-object basis by passing code references to the appropriate object methods.

The prefilter exists to handle common filtering tasks without hogging the lone input filter spot (or requiring users to constantly set input filters for every field). The Rose::HTML::Form::Field prefilter optionally trims leading and trailing whitespace based on the value of the trim_spaces() boolean attribute. This is part of the public API for field objects, so subclasses that override input_prefilter() must preserve this functionality.

In addition to the various kinds of field values, each field also has a name, which may or may not be the same as the value of the "name" HTML attribute.

Fields also have associated labels, error strings, default values, and various methods for testing, clearing, and reseting the field value. See the list of object methods below for the details.

CUSTOM FIELDS

This module distribution contains classes for most simple HTML fields, as well as examples of several more complex field types. These "custom" fields do things like accept only valid email addresses or dates, coerce input and output into fixed formats, and provide rich internal representations (e.g., DateTime objects). Compound fields are made up of more than one field, and this construction can be nested: compound fields can contain other compound fields. So long as each custom field class complies with the API outlined here, it doesn't matter how complex it is internally (or externally, in its HTML serialization).

(There are, however, certain rules that compound fields must follow in order to work correctly inside Rose::HTML::Form objects. See the Rose::HTML::Form::Field::Compound documentation for more information.)

All of these classes are meant to be a starting point for your own custom fields. The custom fields included in this module distribution are mostly meant as examples of what can be done. I will accept any useful, interesting custom field classes into the Rose::HTML::Form::Field::* namespace, but I'd also like to encourage suites of custom field classes in other namespaces entirely. Remember, subclassing doesn't necessarily dictate namespace.

Building up a library of custom fields is almost always a big win in the long run. Reuse, reuse, reuse!

HTML ATTRIBUTES

Rose::HTML::Form::Field has the following set of valid HTML attributes.

accesskey
class
dir
id
lang
name
onblur
onclick
ondblclick
onfocus
onkeydown
onkeypress
onkeyup
onmousedown
onmousemove
onmouseout
onmouseover
onmouseup
style
tabindex
title
value
xml:lang

CONSTRUCTOR

new PARAMS

Constructs a new Rose::HTML::Form::Field object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

clear

Clears the field by setting both the "value" HTML attribute and the input value to undef. Also sets the is_cleared() flag.

default VALUE

Convenience wrapper for default_value()

default_value VALUE

Set the default value for the field. In the absence of a defined input value, the default value is used as the input value.

deflate_value VALUE

This method is meant to be overridden by a subclass. It should take VALUE and "deflate" it to a form that is a suitable for the output value: a string or reference to an array of strings. The implementation in Rose::HTML::Form::Field simply returns VALUE unmodified.

description [TEXT]

Get or set a text description of the field. This text is not currently used anywhere, but may be in the future. It may be useful as help text, but keep in mind that any such text should stay true to its intended purpose: a description of the field.

Going too far off into the realm of generic help text is not a good idea since this text may be used elsewhere by this class or subclasses, and there it will be expected to be a description of the field rather than a description of how to fill out the field (e.g. "Command-click to make multiple selections") or any other sort of help text.

It may also be useful for debugging.

field_name [NAME]

When passed a NAME argument, it sets the name of the field. If the "name" HTML attribute is not defined, its value is also set to NAME. NAME is then returned.

If no arguments are passed, and if the field name is not defined, then the field name is set to the value of the "name" HTML attribute and then returned. If the field name was already defined, then it is simply returned.

Note that this means that the field name and the "name" HTML attribute do not necessarily have to be the same (but usually are).

filter [CODE]

Sets both the input filter and output filter to CODE.

hidden_field

Convenience wrapper for hidden_fields()

hidden_fields

Returns one or more Rose::HTML::Form::Field::Hidden objects that represent the hidden fields needed to encode this field's value.

html

Returns the HTML serialization of the field, along with the HTML error message, if any. The field and error HTML are joined by html_error_separator(), which is "<br>\n" by default.

html_error_separator [STRING]

Get or set the string used to join the HTML field and HTML error message in the output of the html() method. The default value is "<br>\n"

html_field

Returns the HTML serialization of the field.

html_hidden_field

Convenience wrapper for html_hidden_fields()

html_hidden_fields

Returns the HTML serialization of the fields returned by hidden_fields(), joined by newlines.

html_label [ARGS]

Returns the HTML serialization of the label object, or the empty string if the field's label is undefined or zero in length. Any ARGS are passed to the call to label_object().

html_prefix [STRING]

Get or set an HTML prefix that may be displayed before the HTML field. Rose::HTML::Form::Field does not use this prefix, but subclasses might. The default value is an empty string.

html_suffix [STRING]

Get or set an HTML suffix that may be appended to the HTML field. Rose::HTML::Form::Field does not use this suffix, but subclasses might. The default value is an empty string.

html_tag

This method is part of the Rose::HTML::Object API. In this case, it simply calls html_field().

inflate_value VALUE

This method is meant to be overridden by subclasses. It should take VALUE and "inflate" it to a form that is a suitable internal value. (See the OVERVIEW for more on internal values.) The default implementation simply returns its first argument unmodified.

input_filter [CODE]

Get or set the input filter.

input_prefilter VALUE

Runs VALUE through the input prefilter. This method is called automatically when needed and is not meant to be called by users of this module. Subclasses may want to override it, however.

The default implementation optionally trims leading and trailing spaces based on the value of the trim_spaces() boolean attribute. This is part of the public API for field objects, so subclasses that override input_prefilter() must preserve this functionality.

input_value [VALUE]

Get or set the input value.

input_value_filtered

Returns the input value after passing it through the input prefilter and input filter (if any).

internal_value

Returns the internal value.

is_cleared

Returns true if the field is cleared (i.e., if clear() has been called on it and it has not subsequently been reset() or given a new input value), false otherwise.

is_empty

Returns true if the internal value contains any non-whitespace characters. Subclasses should be sure to override this if they use internal values other than strings.

label [STRING]

Get or set the field label. This label is used by the various label printing methods as well as in some default error messages. Even if you don't plan to use any of the former, it might be a good idea to set it to a sensible value for use in the latter.

label_object [ARGS]

Returns a Rose::HTML::Label object with its for HTML attribute set to the calling field's id attribute and any other HTML attributes specified by the name/value pairs in ARGS. The HTML contents of the label object are set to the field's label(), which has its HTML escaped if escape_html() is true (which is the default).

name [NAME]

Get or set the "name" HTML attribute, but return the field_name() if the "name" HTML attribute is undefined.

output_filter [CODE]

Get or set the output filter.

output_value

Returns the output value.

parent_field [FIELD]

Get or set the parent field. This method is provided for the benefit of subclasses that might want to have a hierarchy of field objects. The reference to the parent field is "weakened" using Scalar::Util::weaken() in order to avoid memory leaks caused by circular references.

required [BOOL]

Get to set a boolean flag that indicates whether or not a field is "required." See validate() for more on what "required" means.

reset

Reset the field to its default state: the input value and error() are set to undef and the is_cleared() flag is set to false.

trim_spaces [BOOL]

Get or set the boolean flag that indicates whether or not leading and trailing spaces should be removed from the field value in the input prefilter. The default is true.

validate

Validate the field and return a true value if it is valid, false otherwise. If the field is required, then its internal value is tested according to the following rules.

* If the internal value is undefined, then return false.

* If the internal value is a reference to an array, and the array is empty, then return false.

* If trim_spaces() is true (the default) and if the internal value does not contain any non-whitespace characters, return false.

If false is returned due to one of the conditions above, then error() is set to the string:

$label is a required field

where $label is either the field's label() or, if label() is not defined, the string "This".

If a custom validator() is set, then $_ is localized and set to the internal value and the validator subroutine is called with the field object as the first and only argument.

If the validator subroutine returns false and did not set error() to a defined value, then error() is set to the string:

$label is invalid

where $label is is either the field's label() or, if label() is not defined, the string "Value".

The return value of the validator subroutine is then returned.

If none of the above tests caused a value to be returned, then true is returned.

validator [CODE]

Get or set a validator subroutine. If defined, this subroutine is called by validate().

value [VALUE]

If a VALUE argument is passed, it sets both the input value and the "value" HTML attribute to VALUE. Returns the value of the "value" HTML attribute.

xhtml

Returns the XHTML serialization of the field, along with the HTML error message, if any. The field and error HTML are joined by xhtml_error_separator(), which is "<br />\n" by default.

xhtml_error_separator [STRING]

Get or set the string used to join the XHTML field and HTML error message in the output of the xhtml() method. The default value is "<br />\n"

xhtml_field

Returns the XHTML serialization of the field.

xhtml_hidden_field

Convenience wrapper for xhtml_hidden_fields()

xhtml_hidden_fields

Returns the XHTML serialization of the fields returned by hidden_fields(), joined by newlines.

xhtml_label [ARGS]

Returns the XHTML serialization of the label object, or the empty string if the field's label is undefined or zero in length. Any ARGS are passed to the call to label_object().

xhtml_tag

This method is part of the Rose::HTML::Object API. In this case, it simply calls xhtml_field().

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

Copyright (c) 2004 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.