NAME

Contentment::Form - Defines forms, widgets, and submissions API

DESCRIPTION

The forms API is divided into three primary and persistently stored types: Contentment::Form, Contentment::Form::Widget, and Contentment::Form::Submission. This module currently contains the definition of all three. It is likely that the widget and submission API will be moved into their own modules at some future point. However, Contentment::Form will likely remain the only module you need to load to get access to those classes.

The basic overview is that a "form" is the structure a particular web form takes, i.e., a collection "widgets." The "widgets" are the controls added to a form and provide processing to convert raw variables submitted over HTTP into processed values. The "submission" represents either a prepared form (a particular instance sent to the client) or a submitted form containing raw variables for processing. The submission asks each widget in the form to process the raw variables into processed values. Then, the form's action is asked to do whatever it does on those processed values.

Contentment::Form

This class currently only contains two fields per record: form_name and action. The key, form_name, should be a name unique to that form throughout the entire Contentment web site. This is used to group widgets and submissions together with that particular form. The action is the name of the plugin (see "run_plugin" in Contentment), which is responsible for processing a form submission from this form.

Contentment::Form::Widget

This class defines a form_name and widget_name that are able to uniquely identify each widget---though, in the database, the primary key is the widget_id. The widget then has a class field, in which is stored the name of a class used for processing the widget. That class must define a single process method, which is called with the widget and submission as arguments. Finally, the args field defines the characteristics of the widget as a hash reference.

Contentment::Form::Submission

Submissions form the capstone of the API. Each submission has a uuid, form_name, session_id, ctime, ptime, ftime, map, vars, and results. The uuid is an automatically generated (see Data::UUID) identifier for the submission, which is used to creating forms and for determining which submission is responsible for handling a form submission. The form_name tells the submission which form object it belongs to and, consequently, which widgets apply to it. The session_id is a security feature, which prevents a non-superuser from trying to steal information out of another session's submission. The ctime is a DateTime object containing the submission's creation timestamp. The ptime is a DateTime object contain the timestamp from the last time it was processed (i.e., the last time a submission was made to modify the vars). The ftime is a DateTime object containing the timestamp from when the submission was last processed and the action executed reported a "finished" state. The map names the plugin used to determine which URL to load based upon the state of the submission. The vars is a hash reference containing the processed form values. The results is used to store the output from the last executed action.

EXTRA METHODS

@submissions = Contentment::Form::Submission->create_from_args(%args)

This method attempts to load submission objects from a submitted form. The submissions will have the transient variable alias set to the alias assigned by the submitter and the raw_vars hash will contain the raw values submitted.

$url = $submission->process

This method performs form processing. It runs each form widget against the raw values submitted to the form and then executes the action associated with the form. Finally, it asks the map plugin for a URL and returns the URL.

$widget = Contentment::Form::Widget->build(%args)

This is a shortcut for creating widgets. This method will attempt to load the widget from the form_name and widget_name arguments passed into %args if it can. If not it will create a new widget with those fields set. Then it will set the class and args fields of the widget according to the same values in %args.

$widget->process($submission)

Applies the widget's class processor to the given $submission.

SEE ALSO

Contentment::Form::Widget::Null, Contentment::Form::Widget::Input, Contentment::Form::Widget::Select

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.