NAME

Apache::Wyrd::Form - Build complex HTML forms from Wyrds

SYNOPSIS

  <BASENAME::Form recipient="webmaster@example.com">
    <BASENAME::Form::Template name="enter">
      $:error_block
      <BASENAME::ErrField trigger="name">
        Name:
      </BASENAME::ErrField>
      <BASENAME::Input type="text" name="name" flags="required" />
      <input type="submit" name="action" value="Send Name" />
    </BASENAME::Form::Template>
    <BASENAME::Form::Template name="exit">
      Your name has been mailed to the webmaster.
    </BASENAME::Form::Template>
  </BASENAME::Form>

DESCRIPTION

The Apache::Wyrd::Form (Form) object provides the core mechanism for processing fill-in forms.

The Form requires one or more Apache::Wyrd::Form::Template objects (Templates) which provide, on the same page/url/Location, the pages which make up the complete form.

By default, the form will process these Templates in order, starting with the first enclosed Template in order of appearance in the HTML text, and ending with the last, accepting each set of input from the browser and moving on to the next. On submission of the last page, the form finalizes the process by calling the _submit_data method. This way, a large amount of data can be entered in subsequent browser-pages as if they were the same page and submitted only when the full requisite of data is accumulated. Additionally, there are methods available for conditionally moving between Templates in order to include or exclude a section of the Template-set or range of requirements.

The form maintains the state of the information between Template pages, accumulating them in the (reserved) _variables attribute. If inputs/controls in later Templates have the same name as those in earlier ones, the values submitted in the earlier ones will be the initial values of the later.

Forms have three classes of children: Inputs, Views, and Errors. Forms track the value of and operate on Inputs, meaning Apache::Wyrd::Inputs or derived classes of Apache::Wyrd::Input. Form::View (View) objects show a snapshot of the current state of the form, as a preview, and Form::ErrTag and Form::ErrField objects (Error Flags) indicate on the page which Inputs have illegal values for the requirements of the form. Dev. Note: Although they are all enclosed in a Form::Template Wyrd, all these elements are actually direct children of the Form, because the Template enclosing them becomes the literal body of the form for the browser-server transaction at that point in the sequence. (Form objects use a method called _reload_self to do this.)

Input values can also be initialized via CGI by passing values (in a get or post request) to the Form. There is also a pair of explicit initializers, Apache::Wyrd::Form::Preload and Apache::Wyrd::Form::Defaults, which are placed inside Templates to initialize the values of inputs within that Template. Internally, the _preload_inputs method can be overridden (defined in a subclass) to do the same, and yet another method _extra_preloads can be overridden to preload specific input values.

The Form calls the set method of each of it's Inputs, passing a value to the Input which is derived (in order of priority) by checking to see if the input can provide a current_value, seeing if it has a method defined for that purpose, _param_process_foo where "foo" is the name of the parameter, or lastly, by checking the CGI environment for the value. Dev. Note: Inputs also have a priority by which they attempt to establish default values for themselves based on defaults or the current CGI environment if the Form is unable to determine one for them, as is the case on Form entry pages. See the documentation for Apache::Wyrd::Input.

Internally, the form also manipulates the CGI environment to make the use of image-buttons more convenient. It searches for CGI parameters by the name of foo.x and sets value of the parameter action to "foo". This allows to set an action parameter simply by naming the image button to the name of the action you would like it to perform. For example, the following input will cause an Apache::Wyrd::Form object to set the value of the CGI parameter action to "cancel":

        <input type="image" src="/images/cancel.gif" name="cancel">

Before advancing to the next Template in the sequence, the form will check every input in turn to see if it has returned an error. Errors are compiled, and if they number more than zero, the submitted Template will be reloaded, setting any Error Flag triggered by the Input. If there are no errors, the Form moves on to the next Template. If there are no more templates, it submits all its accumulated data via the _submit_data method.

No matter which template is the current one, the Form will also complete the transaction by setting any placemarkers inside the template which match the name of one of the _globals keys. By so doing, the programmer can set a global at any point in the form handling system and expect that global to show in it's placemarked area in the HTML of the form.

Among the standard globals is the error_block global, which represents where to put the block of error messages on the page of the form. In other words if $:error_block does not appear on the template, there will be no error_block shown on the form.

HTML ATTRIBUTES

action

Same as the action attribute of the HTML <form> tag. If this is the location of a page with a different Form object on it, the form sequence will continue with all accumulated data to that location. Note, however, that any new data (that is, data entered on the template from which the action is triggered) will need to be received and vetted by the next form, not this form. This can be done by putting appropriate Input objects in the receiving form.

If not provided, the default, and generally much simpler, action value is a reference to the current page.

method

Same as the method attribute of the HTML <form> tag.

recipient

When using the default behavior, submits the information via email to this recipient in the form of an XML dump.

flags

check_resets

Check for the submission of a "reset" button by checking that the parameter action is set to "reset". Resets the whole form to it's default state.

continue

Keep accumulated data past the _submit() method and insert it in the final form page. This allows that page to be used as a continuation point to another form. Note that the action attribute must be set to the location of the continuation page.

ignore_errors

Proceed through the Templates from one to the next even if there are input errors.

no_collapse

Show all error messages, even if there are more than one identical message.

no_grow

Do not add the formname to the URL of each step to mark the passage from one form to the next. The default behavior is to do so so as to avoid any weirdness with odd browsers.

no_submit

Do not submit the form. Useful for forms for "control panel" style forms that shift the state of the page while retaining that state.

preload

Checks for preloaded values. Set automatically by an Apache::Wyrd::Form::Preload object.

HIDDEN ATTRIBUTES

Because of the complexity of the Apache::Wyrd::Form object, explanations of these internal attributes are provided to aid development of subclasses.

_variables

hashref of all input/form values, loaded first from the storage variable, then from the CGI environment.

_globals

hashref of private variables for the given form. By default, the form will have any matching Apache::Wyrd::Interfaces::Setter-style placemarkers set to these values.

_input_index & _input

Inputs are stored in arrayref to support multiple inputs of the same variable. Hence, unique names need to be used in an index to indicate a given member of the arrayref _input.

_errortag_index & _errortag

Errortags are conditionally-varying elements of the form usually indicating errors.

_view_index & _view

Views are set-style templates used for showing the current state of the form on the page.

_errors

flags for particular error conditions, stored in an arrayref. This array is checked against registered triggers for errortags. Errors are defined as arbitrary strings signifying an error event such as "preview" or "no full name". Note that as soon as an error is inserted, the form will not advance to the next template until the error is corrected (unless, of course, the ignore_errors flag is set).

_error_messages

arrayref of strings to be displayed to the user explaining what error conditions have occurred and how to fix them.

_current_identifier

which of the multiple forms is the current focus. Will normally change during any given run of the Form object as one form is approved and the next is loaded.

_form & _form_index

Forms are individual "states" that the form is in, usually signifying the process of filling out each step of a multiple-page form.

_action_index

Hashref holding the action to put into the form tag when using that form as the current form.

_next_form, _current_form, & _last_form

self explanatory place markers used in deciding where in the sequence of forms the user is.

PERL METHODS

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

(void) drop_var (scalar)

Remove a parameter from the tracked state.

(void) insert_error (scalar)

Add a "trigger" to the error register. In the most usual case where the error indicates illegal input, this is the parameter name, but may represent a more complex error condition, such as a scheduling conflict or unbalanced set of figures.

(void) insert_error_messages (array[ref])

Insert an error message into the error message queue. The queue is processed by the _dump_errors method.

(void) register_form (Apache::Wyrd::Form::Template)

Add a form Template to this form object. Called by Apache::Wyrd::Form::Template to build the form sequence. Also notes the action attribute of the template, which can override the default or given action of the Form.

(void) register_errors (Apache::Wyrd::Input)

Same as insert_error, except the argument is an Input object who's errors are inserted.

(void) register_error_messages (Apache::Wyrd::Input)

Same as insert_error_messages, except the argument is an object who's (possibly multiple) errors are inserted.

(void) register_input (Apache::Wyrd::Input)

Register an input to be tracked by this form. See Apache::Wyrd::Input

(void) register_errortag (Apache::Wyrd::ErrTag)

Register an ErrorTag-like object to be tracked by this form. See Apache::Wyrd::ErrTag or Apache::Wyrd::ErrField.

(void) register_view (Apache::Wyrd::ErrTag)

Register a View-like object to be tracked by this form. See Apache::Wyrd::Form::View.

(void) set_var (scalar)

Set the value of the given parameter in the tracked state.

HOOK METHODS

(void) _interpret_action (void)

Called during the _setup phase. Default behavior is to interpret any image-type inputs into the param action.

(scalar) _format_error (scalar)

Format an error message. To be used with _format_error_block to format the error message on the page. These are compiled into a block during the _format_output phase. Default behavior is to return the error as an HTML line-item.

(scalar) _format_error_block (scalar)

Format the block of error messages. To be used with _format_error_block to format the error message on the page. Default behavior is to return the error as an HTML unordered list with the text: "The following problems were found:" and "Please correct the items marked before continuing" around it. The default behavior assumes the CSS style .error is defined to mark errors. See Apache::Wyrd::ErrField.

(void) _dispatch_errors (void)

This method handles how the errors will be sent to the page. The default is to set the global placemaker "error_block" to the value of the error block, so this placemarker must be somewhere in the current Form Template in order to show on the page.

(void) _prep_submission (void)

If the default _submit_data method is used, this provides a hook for altering the data prior to submitting it.

(void) _submit_data (void)

Submit the accumulated data. All variables should be in the _variables attribute at the time this method is called. By default, it will attempt to mail an XML dump of the data if the recipient attribute is set. If not, it will dump the data to STDERR (the Apache error log).

(void) _prep_preloads (void)

Hook for altering preloads before executing them. Called during the _format_output phase.

(void) _extra_preloads (void)

Hook for additional preloads. Called during the _format_output phase.

(void) _activate_widgets (void)

Hook for activating special controls. Called during the _format_output phase.

(void) _check_form (void)

Hook for inserting special error conditions for form-wide events, such as a running total that violates a special rule. Called during the _format_output phase.

(void) _check_reset (void)

Determine if a reset condition is reached. By default, checks to see if the action parameter is set to "reset" and the check_reset flag is set.

(void) _check_form (void)

Hook for inserting special error conditions for global events, or for altering global values before continuing with processing the form.

This is also a good place to do flow control when pages in a template sequence may conditionally need to be skipped, or where flow is to be directed to a form on a new page.

Example:

    sub _check_form {
        my ($self) = @_;
        if ( ($self->{_current_form} eq 'fourthpage') ) {
            if ($self->{_variables}->{skip_page_5}) {
                #
                #if the skip_page_5 variable is set, move on to page 6.
                $self->{_next_form} = 'sixthpage';
                #
            } elsif ($self->{_variables}->{validity} eq 'invalid') {
                #
                #if the value of "validity" is "invalid", move on to the
                #validity restoration form.
                return $self->dbl->req->internal_redirect_handler('/restore_validity.html');
                #
            }
        }
    }

(scalar) _storage_template (void)

HTML format for the state-storage hidden variable. By default is a simple hidden input.

(scalar) _submitted (void)

Has the form been submitted yet, or are we on the first page? If altered, be sure to alter _proof_of_submit as well.

(scalar) _proof_of_submit (void)

HTML format for the proof of submit hidden variable. By default is a simple hidden input with the param name _submitted.

OTHER RESERVED METHODS

The Form object also reserves the methods _dump_errors, _fire_triggers, _unpack_data, _pack_data, _preload_inputs, _check_inputs, _check_errors, _reload_form, _get_value, _wrap_form, _current_marker, register_child, and _set_children.

BUGS/CAVEATS/RESERVED METHODS

Reserves the _setup, the _format_output, AND the _generate_output method. Subclassing is done via the other hooks, above.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

LICENSE

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

See LICENSE under the documentation for Apache::Wyrd.

cpanm Apache::Wyrd

perl -MCPAN -e shell
install Apache::Wyrd