Namespace form

Commands for managing dynamic templated forms.

Method Summary

Method Detail

* indicates required

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.

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.

Initialize the data structures for a form. Parameters: id * A keyword identifier for the form, such as { add_user} or { edit_item} . The ID must be unique in the context of a single page. Options: method The standard METHOD attribute to specify in the HTML FORM tag at the beginning of the rendered form. Defaults to POST. html A list of additional name-value attribute pairs to include in the HTML FORM tag at the beginning of the rendered form. Common attributes include JavaScript event handlers and multipart form encoding. For example, { -html { enctype multipart/form-data onSubmit validate() } } elements A block of element specifications.

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

Return the number of elements in a form Parameters: id * The form identifier

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

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

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

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, retrieve all form elements

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.

Private Methods:

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.

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

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

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.

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.

* indicates required