NAME

SYNOPSIS

    package MyField;

    use base '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

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

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.

HIERARCHY

A field is an abstraction for a collection of one or more HTML tags, including the field itself, the field's label, and any error messages. Each of these things may be made up of multiple HTML elements, and they usually exist alongside each other rather than nested within each other. As such, the field itself cannot rightly be considered the "parent" of these elements. This is why the child-related methods inherited from Rose::HTML::Object (children, descendants, etc.) will usually return empty lists. Furthermore, any children added to the list will generally be ignored by the field's HTML output methods.

Effectively, once we move away from the Rose::HTML::Object-derived classes that represent a single HTML element (with zero or more children nested within it) to a class that presents a higher-level abstraction, such as a form or field, the exact population of and relationship between the constituent HTML elements may be opaque.

If a field is a group of sibling HTML elements with no real parent HTML element (e.g., a radio button group), then the individual sibling items will be available through a dedicated method (e.g., radio_buttons).

In cases where there really is a clear parent/child relationship among the HTML elements that make up a field, such as a select box which contains zero or more options or option groups, the children method will return the expected list of objects. In such cases, the list of child objects is usually restricted to be of the expected type (e.g., radio buttons for a radio button group), with all child-related methods acting as aliases for the existing item methods. For example, the add_options method in Rose::HTML::Form::Field::SelectBox does the same thing as add_children. See the documentation for each specific Rose::HTML::Form::Field-derived class for more details.

CUSTOM FIELDS

(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

    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

auto_invalidate_parent [BOOL]

Get or set a boolean value that indicates whether or not the value of any parent field is automatically invalidated when the input value of this field is set. The default is true.

See "parent_field" and "invalidate_value" for more information.

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.

description_id [ID [, ARGS]]

Get or set an integer message id for the description.

Get or set an integer message id for the description. When setting the message id, an optional ARGS hash reference should be passed if the localized text for the corresponding message contains any placeholders.

error_label [STRING]

Get or set the field label used when constructing error messages. For example, an error message might say "Value for [label] is too large." The error label will go in the place of the "[label]" placeholder.

If no error label is set, this method simply returns the label.

error_label_id [ID [, ARGS]]

Get or set an integer message id for the error label. When setting the message id, an optional ARGS hash reference should be passed if the localized text for the corresponding message contains any placeholders.

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

Returns the error text, if any, as a snippet of HTML that looks like this:

    <span class="error">Error text goes here</span>
    

If the escape_html flag is set to true (the default), then the error text has any HTML in it escaped.

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

In scalar context, returns the HTML serialization of the fields returned by hidden_fields(), joined by newlines. In list context, returns a list containing the HTML serialization of the fields returned by hidden_fields().

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

If required()is true for this field, then the name/value pair "class => 'required'" is passed to the call to label_object() before any arguments that you pass. This allows you to override the "class" value with one of your own.

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.

invalidate_output_value

Invalidates the field's output value, causing it to be regenerated the next time it is retrieved. This method is useful if the output value is created based on some configurable attribute of the field (e.g., a delimiter string). If such an attribute is changed, then any existing output value must be invalidated.

invalidate_value

Invalidates the field's value, causing the internal and output values to be recreated the next time they are retrieved.

This method is most useful in conjunction with the "parent_field" attribute. For example, when the input value of a subfield of a compound field is set directly, it will invalidate the value of its parent field(s).

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 false if the internal value contains any non-whitespace characters or if trim_spaces is false and the internal value has a non-zero length, true otherwise. Subclasses should be sure to override this if they use internal values other than strings.

is_full

Returns true if the internal value contains any non-whitespace characters, false otherwise. 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 error messages (assuming there is no explicitly defined error_label. 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_id [ID]

Get or set an integer message id for the field label.

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

local_name [NAME]

Get or set the name of this field from the perspective of the parent_form or parent_field, depending on which type of thing is the direct parent of this field. The local name should not change, regardless of how deeply this field is nested within other forms or fields.

message_for_error_id PARAMS

Return the appropriate message object associated with the error id. The error id, message class, and message placeholder values are specified by PARAMS name/value pairs. Valid PARAMS are:

name [NAME]

If passed a NAME argument, then the local_name is set to NAME and the "name" HTML attribute is set to the fully-qualified field name, which may include dot (".") separated prefixes for the parent forms and/or parent fields.

If called without any arguments, and if the "name" HTML attribute is empty, then the "name" HTML attribute is set to the fully-qualified field name.

Returns the value of the "name" HTML attribute.

output_filter [CODE]

Get or set the output filter.

output_value

Returns the output value.

parent_field [FIELD]

Get or set the parent field. The parent field should only be set if the direct parent of this field is another field. The reference to the parent field is "weakened" using Scalar::Util::weaken() in order to avoid memory leaks caused by circular references.

parent_form [FORM]

Get or set the parent form. The parent form should only be set if the direct parent of this field is a form. The reference to the parent form is "weakened" using Scalar::Util::weaken() in order to avoid memory leaks caused by circular references.

parent_group [GROUP]

Get or set the parent group. Group objects are things like Rose::HTML::Form::Field::RadioButtonGroup and Rose::HTML::Form::Field::CheckboxGroup: conceptual groupings that have no concrete incarnation in HTML. (That is, there is no parent HTML tag wrapping checkbox or radio button groups.)

The parent group should only be set if the direct parent of this field is a group object. The reference to the parent group is "weakened" using Scalar::Util::weaken() in order to avoid memory leaks caused by circular references.

prepare

Prepares the field for use in a form. Override this method in your custom field subclass to do any work required for each field before each use of that field. Be sure to call the superclass implementation as well. Example:

    package MyField;
    use base 'Rose::HTML::Form::Field';
    ...
    sub prepare
    {
      my($self) = shift;

      # Do anything that needs to be done before each use of this field
      ...

      # Call superclass implementation
      $self->SUPER::prepare(@_);
    }
    

rank [INT]

Get or set the field's rank. This value can be used for any purpose that suits you, but it is most often used to number and sort fields within a form using a custom compare_fields() method.

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

Returns the error text, if any, as a snippet of XHTML that looks like this:

    <span class="error">Error text goes here</span>
    

If the escape_html flag is set to true (the default), then the error text has any HTML in it escaped.

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

In scalar context, returns the XHTML serialization of the fields returned by hidden_fields(), joined by newlines. In list context, returns a list containing the XHTML serialization of the fields returned by hidden_fields().

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

If required()is true for this field, then the name/value pair "class => 'required'" is passed to the call to label_object() before any arguments that you pass. This allows you to override the "class" value with one of your own.

xhtml_tag

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

SUPPORT

<http://groups.google.com/group/rose-html-objects>

Although the mailing list is the preferred support mechanism, you can also email the author (see below) or file bugs using the CPAN bug tracking system:

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-HTML-Objects>

There's also a wiki and other resources linked from the Rose project home page:

<http://rosecode.org>

AUTHOR

LICENSE