Namespace form
Commands for managing dynamic templated
forms.
Method Summary
Listing of public methods:
Method Detail
* indicates required
Public Methods:
|
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 |
|
|
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:
|
|
Return true if a submission in progress. The submission
may or may not be valid.
-
Parameters:
- 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:
- 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:
- 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:
|
|
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