Namespace form

Commands for managing dynamic templated forms.

Method Summary

template::form::create
template::form::exists
template::form::export
template::form::get_combined_values
template::form::get_values
template::form::is_request
template::form::is_submission
template::form::is_valid
template::form::section
template::form::set_values

Method Detail

* indicates required

template::form::exists

Determine whether a form exists by checking for its data structures. Parameters: id * The ID of an ATS form object. Returns: 1 if a form with the specified ID exists. 0 if it does not.

template::form::export

Generates hidden input tags for all values in a form submission. Typically used to create a confirmation page following an initial submission. Returns: A string containing hidden input tags for inclusion in a form.

template::form::get_combined_values

Return a list which represents the result of getting combined values from multiple form elements Parameters: id * The form identifier args * A list of element identifiers. Each identifier may be a regexp. For example, form get_combined_values { foo.*} will combine the values of all elements starting with { foo} return * The combined list of values

template::form::get_values

Set local variables for form variables (assume they are all single values). Typically used when processing the form submission to prepare for DML or other type of transaction. Parameters: id * The form identifier args * A list of element identifiers. If the list is empty, retreive all form elements

template::form::is_request

Return true if preparing a form for an initial request (as opposed to repreparing a form that is returned to the user due to validation problems). This command is used to conditionally set default values for form elements. Parameters: id * The form identifier Returns: 1 if true or 0 if false

template::form::is_submission

Return true if a submission in progress. The submission may or may not be valid. Parameters: id * The form identifier Returns: 1 if true or 0 if false

template::form::is_valid

Return true if submission in progress and submission was valid. Typically used to conditionally execute DML and redirect to the next page, as opposed to returning the form back to the user to report validation errors. Parameters: id * The form identifier Returns: 1 if true or 0 if false

template::form::section

Set the name of the current section of the form. A form may be divided into any number of sections for layout purposes. Elements are tagged with the current section name as they are added to the form. A form style template may insert a divider in the form whenever the section name changes. Parameters: id * The form identifier. section * The name of the current section.

template::form::set_values

Convenience procedure to set individual values of a form (useful for simple update forms). Typical usage is to query a onerow data source from database and pass the resulting array reference to set_values for setting default values in an update form. Parameters: id * The form identifier array_ref * The name of a local array variable whose keys correspond to element identifiers in the form

Private Methods:

template::form::check_elements

Iterates over all declared elements, checking for hidden widgets and rendering those that have not been rendered yet. Called after rendering a custom form template as a debugging aid. Parameters: id * The form identifier

template::form::generate

Render the finished HTML output for a dynamic form. Parameters: id * The form identifier style * The style template to use when generating the form. Form style templates must be placed in the forms subdirectory of the ATS resources directory. Returns: A string containing the HTML for the body of the form.

template::form::get_reference

Helper procedure used to access the basic data structures of a form object. Called by several of the form commands.

template::form::render

Render the HTML FORM tag along with a hidden element that identifies the form object. Parameters: id * The form identifier tag_attributes * A name-value list of special attributes to add to the FORM tag, such as JavaScript event handlers. Returns: A string containing the rendered tags.

template::form::template

Auto-generate the template for a form Parameters: id * The form identifier style * The style template to use when generating the form. Form style templates must be placed in the forms subdirectory of the ATS resources directory. Returns: A string containing a template for the body of the form.

* indicates required