Pageform - a meta-module for xaraya forms

Overview

Using Pageform you can:

• Organize form pages and actions in sequence
• Define form fields via a DD object
• Utilize custom DD form templates, with alternative layouts
  
• Utilize built in DD property validation on field values
• Have required fields
• Write custom reset, validation and processing for the entire form, via function and/or php snippets
• Provide custom error messages on invalid fields
  
• Cache form field values so you can return to the form with previous info filled in
• Exposes field details for client side JS validation and preprocessing
  
• Troubleshoot with debug options

Pageform requires the dynamidata (DD) and xarpages modules (dynamicdata is a core Xaraya module, and xarpages is part of the base package). This document assumes some working knowledge of these modules.

Once setup, it's really not very complicated to use, provided you understand how to use dynamic data and xarpages. In fact, I've found it incredibly convenient.

Note: I could have made this its own module, and perhaps might one day, but building on top of xarpages and DD allows us to use many existing features and avoid redundant code. One approach might be to make a module that simply does the install so you dont have to do that manually (as described below).

How To Use It

First follow the installation instructions below to create the page types and copy the custom functions.

There are two page types:

• pageform - contains the form
• pageaction - processes the form

You will create an ordered sequence of pageform--pageaction pages. This sequence of pages must be contained as child pages in the xarpages hierarchy under a single parent page (the parent can be empty, however).

For example you might have pages arranged as:

intro page (type html)
|
|-------- form page (type pageform)
|
|-------- action page (type pageaction)
|
|-------- results page (type pageform)

Pageform pages present the form. The form is then submitted to a pageaction page, which fetches the Post data, validates the values, and processes the data. If any values are invalid, they are not processed and you're sent back to the form with error messages.

There are several validation steps followed in sequence: a. fetch and validate using the property's checkInput method (uses the validations defined in the object's properties), b. make sure the required fields are not empty, and then c. custom validation php snippet and/or php function call.

Once validated, the data can be processed. You may enter short php snippets in the page, or call a php function.

Finally, the pageaction redirects to the next pageform page in the sequence. This can be any page type, but if you want the preceeding pageaction to pass along some info, it could be another pageform page so that it has an object to receive the data results.

Note, we never actually create a DD object in the database. We just use the itemtype to define the field properties, validations, and input forms. Therefore, you do not need to create an itemid field on these objects.

Briefly, to make a form and process it, you do the following (minimally):

1. Create a DD object defining the properties that make up the fields in your form.
   
2. Create an xarpage that will be the parent of your forms pages (e.g. page type: HTML).
3. Create an xarpage to contain your form (page type: pageform), with its 'data' field set the dd item type.
4. Create an xarpage to contain your action (page type: pageaction), and write some php code to process the data.
5. Create an xarpage to show the results (e.g. page type: pageform).

By default, pageform uses the DD showform.xd template. You can provide your own object specific template, such as mytheme/modules/dynamicdata/objects/showform-myobject.xt, to format the form, or to select specific fields to present to the user.

On the pageaction page, if you check the Debug box, it will dump the posted values.