NAME

Apache::Wyrd::Input - Form Input Wyrds (scalar)

SYNOPSIS

    <BASENAME::Input type="text" name="foo" flags="required" />

    <BASENAME::Input type="textarea" name="desc" height="100" width="100">
      This is the default text
    </BASENAME::Input>

    <BASENAME::Input type="hidden" name="name" value="lenore" />

    <BASENAME::Input type="password" name="name" size="10" />

    sub _startup_integer {
        my ($self, $value, $params) = @_;
        $self->{'_datum'} ||=
          Apache::Wyrd::Datum::Integer->new($self->{'value'}, $params);
        $self->{'_template'} ||= '<input type="text" name="$:name" ' .
          'value="$:value"?:size{ size="$:size"}?:id{ id="$:id"}' .
          '?:readonly{ readonly}>';
        $self->{'_smart_type'} = 'text';
    }

        <BASENAME::Input type="integer" default="1" name="counted" />

DESCRIPTION

This is the base class for Input objects, which are tracked and affected by the Apache::Wyrd::Form (Form) objects that enclose them. The base Input object is meant to replace, in most cases, the input HTML objects:

• text inputs

• password inputs

• textarea inputs

• hidden inputs

For these, set the type attribute to text, password, textarea, and hidden respectively. Another hybrid input is plaintext, which both shows the text and includes it in the form as a hidden input. For other input types, such as radiobuttons, checkboxes, selection sets, etc., see Apache::Wyrd::Input::Set.

The Input does its work in the _format_output phase. If given a type of "foo", it will first attempt to match it to one of the standard types, then look for a startup_foo method and if it finds it, will call the method. This is to allow derived Input objects to initialize builtins, if needed, without re-implementing the whole _format_output method.

Any derived startup_foo method should, for completeness, set the _datum attribute to a Datum object appropriate to the type, put together a template for the input appropriate to the expected output, and if the Apache::Wyrd::Interfaces::SmartInput interface is to be used, set the _smart_type attribute to the appropriate one for the template. See the SYNOPSIS for an example startup routine for integer types.

For entry pages to Forms or any other state where the enclosing Form cannot determine the initial value of an input, the Input will try the current value it would be getting from a submission now (typically by using a CGI parameter of the same name), any previous submissions (in this form sequence) of variables of the same name, and lastly the "default" value before giving up and initializing to null.

HTML ATTRIBUTES

regular attributes

Most Input objects also accept the attributes of their HTML counterparts. For example, text-type Inputs accept name, value, size, class, id, maxlength, tabindex, accesskey, onchange, onselect, onblur, etc. Dev Note: Derived classes should maintain this support by including conditionals in the template (see the code).

description

A description for this input, to be used in error messages.

maxlength

Maximum length of the inputted text, applies both to text and textarea type Inputs.

name

Required. The name of the Input.

param

The CGI parameter to use for this Input, if not the name.

triggers

The triggers fired (comma separated list) by this input if invalid, if not param or name (in that order of precedence).

width

Width of the item, in pixels. This is an estimated value based on the browser in use and assuming default style-sheets for those browsers. Meant for really quick-and-dirty formatting. Applies only to text and textarea Inputs, or Inputs that somehow make use of the Apache::Wyrd::Interfaces::SmartInput interface.

height

With the same caveats as width, this attribute is the height of the item, in pixels. As with width, applies only to textarea attributes or SmartInputs that implement a height in chars.

type

Required. The type of the Input.

flags

allow_zero

By default, a value of zero is not considered a valid value, and a value of zero will trigger an error if the required flag is set. This flag will allow values that are mathematically equivalent to zero. It may become the default behavior in future versions of this Wyrd.

escape

Escape the HTML of the value, so as to avoid HTML parsing errors. Default behavior for Inputs who's end-result input tags have this problem, such as <input type="text">

no_fail

Always accept value, even when invalid.

not_null

an alias for required.

quiet

Do not report error messages, only errors.

required

trigger an error if empty

reset

Do not track the value of this input, but allow it to be reset on every submit (used in some no_submit flagged forms).

strict

Enforce the strict pragma on the underlying datum object. Of limited use outside of debugging Input objects.

PERL METHODS

(format: (returns) name (arguments after self))

(scalar) name/type/value/description/param (void)

Input has read-only methods for name, type, value, description, triggers, and param. The param attribute is optional for Inputs which might need to use another name than the CGI variable of their associated HTML input, such as to use 'username' and 'password' when the browser may attempt to auto-fill these values.

Note that the value call gets the current value of the input from the underlying _datum object, and not from it's temporary storage under the _value attribute. This allows the Datum to be independent of the temporary value of the Input.

(scalar) null_ok (void)

In rare cases (a number of checkboxes, for example), the Form Wyrd being unable to find the params associated with this input. Normally, the Form Wyrd will consider this an error, and refuse to alter the value of the associated variable. Setting a positive value for null_ok will allow the unfound parameter to indicate a null value (such as when all checkboxes are unchecked) You should not normally have to use this feature.

(void) set (varies)

set accepts a value, which is converted to the appropriate type (arrayref, scalar, etc.) to safely pass the next test, which is the _check_param internal method. If _check_param returns a null result, it is assumed to have failed and the appropriate error calls are made, setting error flags in the parent via the parent's register_errors and register_error_messages.

In the parent, register_errors is assumed to process the triggers and register that at least one error has occurred in submitting it's inputs. register_error_messages is called separately, as there may not be a one-to-one correspondence between what the Input should warn the user about and what it considers an error.

The no_fail flag prevents the errors from registering at all, while the quiet flag will suppress only the error messages.

However, pass or fail, a call to the _datum object will occur with the set call, and presumably, the Datum class will know how to deal with that. For it's own purposes, however, the value will be temporarily stored by the Input, and HTML esacaped if the escape flag is set.

(void) _parse_options (void)

_parse_options looks to the options attribute, which may be explicit as a comma/whitespace delineated list or built up by sub-objects (see Apache::Wyrd::Input::Opt) in order to determine what options to give to the datum object. If this value is already a hashref or arrayref, it does no further processing. Otherwise it attempts to separate the words of the options attribute, using an optional regexp under the "delimiter" attribute.

(scalar) _check_param (scalar)

the _check_param method itself, by default, calls the check method of the underlying Datum instance. Datum returns two values, the first indicating pass/fail for defined/undefined and the second indicating what the default error message is. Authors producing Datum objects created to support the Input should pay special attention to this, as this is where useful error messages can be generated, rather than the default "Invalid data in <param-name>". _check_param also adds the parameter/name as a token to the error register so it can be tracked by the parent.

A shorthand for adding this method to an item is the description attribute, which will be prepended to the error string if an error occurs.

the values stored in the _errors and _error_messages registers can be accessed read_only through the errors and error_messages methods, as demonstrated by the Form object.

(scalar) errors (void)

Return all the errors for this Input. Should be considered as "triggers" of an Apache::Wyrd::Form object for the Apache::Wyrd::ErrTag objects to detect (see documentation for those modules).

(scalar) error_messages (void)

Return all the error messages for this Input.

(scalar) _escape (scalar)

the _escape method is a utility for escaping the data in an HTML text-type input in order to avoid formatting errors. The default is to only escape quotes and ampersands by encoding them as the appropriate entity.

(scalar) _escape (scalar)

the _unescape method reverse-mirrors the _escape method exactly.

(scalar) _template_foo (scalar)

the _template methods should provide an Apache::Wyrd::Interfaces::Setter-style template for a given input. Built-in templates are text, textarea, password

BUGS/CAVEATS/RESERVED METHODS

Reserves the _format_output and _generate_output methods. Also reserves the final_output method.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::Form

Build complex HTML forms from Wyrds

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.