NAME

XAO::DO::Web::FilloutForm - support for HTML forms

DESCRIPTION

Fill out form object. Helps to create fill-out forms for registration and so on. Checks that parameters are Ok and then displays either form or thanks.

Must be overriden with something which will put 'fields' parameter into $self. Format is as array of hash references reference of the following structure:

 [ { name       => field name,
     required   => 0 || 1,
     style      => selection || text || textarea || email || phone ||
                   integer || dollars || real,
     maxlength  => maximum length,
     minlength  => minimum length,
     param      => name of parameter for form substitution,
     text       => description of parameter,
   },
   { ... }
 ]

If you do not care in what order fields are checked you can also supply 'fields' as a hash reference:

 { name => {
       required     => 0 || 1,
       style        => selection || text || textarea || email || phone ||
                       integer || dollars || real,
       maxlength    => maximum length,
       minlength    => minimum length,
       param        => name of parameter for form substitution,
       text         => description of parameter,
   },
   name1 => { ... }
 }

When form filled out "form_ok" method is called, which must be overridden in inherited object to do something good with results. Alternatively reference to subroutine can be given through 'setup' method. This is suitable for using FilloutForm object without overriding it.

Displays form with PARAM.VALUE set to value, PARAM.NAME - to name, PARAM.TEXT - to text, PARAM.REQUIRED to the 0/1 required flag, and PARAM.HTML - to piece of HTML code if applicable (Country selection for example).

METHODS

new (%)

Overrided new method for those who prefer to use inheritance style.

setup_fields (%)

Copying fields descriptions. We copy entire structure here because it could be persistent and we do not want original data to be modified.

display (%)

Displaying the form.

field_desc ($)

Returns field description by name. This is the correct way to get to the value of a field from check_form() or form_ok() methods.

If the optional second parameter set to true then on failure to find the field the method will return undef instead of throwing an error.

field_names ($)

Returns field a list of all field names in the current form.

form_ok

Default handler for filled out form. Must be overriden!

pre_check_form (%)

Pre-checking form. May be used if some values are calculated or copied from another and should be checked later.

Should stuff generated values into {'newvalue'} parameter.

countries_list ()

Returns list of countries for selection. May be overriden if site needs only a fraction of that.

us_continental_states_list ()

Returns list of US continental states for selection. May be overriden if site needs only a fraction of that.

us_states_list ()

Returns list of US states for selection. May be overriden if site needs only a fraction of that.

cc_validate (%)

Returns error text if card number is invalid. Only checksum and consistence with card type is checked.

Card number is taken from 'number' argument and card type from 'type' argument (optionally).

Will store card number into a scalar reference given by 'validated' argument, if it exists and the card validates. Will store card type code into scalar reference given by 'typecode' argument if it exists and the card validates. Codes are:

 VI -- Visa
 AE -- American Express
 MC -- Mastercard
 DC -- Discover

AUTHORS

Copyright (c) 2005 Andrew Maltsev

Copyright (c) 2001-2004 Andrew Maltsev, XAO Inc.

<am@ejelta.com> -- http://ejelta.com/xao/