form is really template::form although when in the "template" namespace you may omit the template:: DEPRECATED: no, you should not omit the namespace, and this proc does not comply with OpenACS naming convention.

Parameters:

command (required)

See Also:

• template::form
• template::element

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

template::form command invokes form functions. Please see the individual functions for their arguments. The template::element API is used to manipulate form elements.

Parameters:

command (required)

See Also:

• template::form::create
• template::form::get_button
• template::form::get_action
• template::form::set_properties
• template::form::get_properties
• template::form::exists
• template::form::get_combined_values
• template::form::get_values
• template::form::get_elements
• template::form::get_errors
• template::form::set_error
• template::form::is_request
• template::form::is_submission
• template::form::is_valid
• template::form::section
• template::form::set_values
• template::form::size
• template::element

Partial Call Graph (max 5 caller/called nodes):

Testcases:

template_widget_file

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 (required)

The form identifier

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Initialize the data structures for a form.

Parameters:

id (required)

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 use for this option is to set multipart form encoding by specifying "-html { enctype multipart/form-data }". Please note that to comply with newer security features, such as CSP, one should not specify JavaScript event handlers here, as they will be rendered inline.

-mode

If set to 'display', the form is shown in display-only mode, where the user cannot edit the fields. Each widget knows how to display its contents appropriately, e.g. a select widget will show the label, not the value. If set to 'edit', the form is displayed as normal, for editing. Defaults to 'edit'. Switching to edit mode when a button is clicked in display mode is handled automatically.

-cancel_url

A url to redirect to when the user hits the Cancel button. If you do not supply a cancel_url, there will be no Cancel button.

-cancel_label

The label of the Cancel button, if cancel_url is supplied. Default is "Cancel".

-actions

A list of actions available on the form, which in practice means a list of buttons to show when the form is in display mode. The value should be a list of lists, with the first element being the form label and the second element being the name of the form element. Defaults to { { "Edit" edit } }. The name of the button clicked can be retrieved using template::form::get_button. The name of the button clicked while in display mode is called the 'action', and can be retrieved using template::form::get_action. The action is automatically carried forward to the form submission, so that the value that you get from calling template::form::get_action on the final form submission is the name of the button which was called when the form changed from display mode to edit mode.

-display_buttons

List of buttons to show when the form is in display mode. Equivalent to actions. If both actions and display_buttons are present, 'actions' is used. 'display_buttons' is deprecated.

-edit_buttons

List of buttons to show when the form is in edit mode. The value should be a list of lists, with the first element being the button label and the second element being the name. Defaults to { { "Ok" ok } }. The name of the button clicked can be retrieved using template::form::get_button.

-has_submit

Set to 1 to suppress the OK or submit button automatically added by the form builder. Use this if your form already includes its own submit button.

-has_edit

Set to 1 to suppress the Edit button automatically added by the form builder. Use this if you include your own.

-elements

A block of element specifications.

-show_required_p

Should the form template show which elements are required. Use 1 or t for true, 0 or f for false. Defaults to true.

See Also:

• template::form::get_button
• template::form::get_action

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Determine whether a form exists by checking for its data structures.

Parameters:

id (required)

The ID of an ATS form object.

Returns:

1 if a form with the specified ID exists. 0 if it does not.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Render the finished HTML output for a dynamic form.

Parameters:

id (required)

The form identifier

style (optional)

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Find out which action is in progress. This is the name of the button which was clicked when the form was in display mode.

Parameters:

id (required)

The ID of an ATS form object.

Returns:

the name of the action in progress

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Find out which button was clicked

Parameters:

id (required)

The ID of an ATS form object.

Returns:

the name of the button clicked

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Return a list which represents the result of getting combined values from multiple form elements

Parameters:

id (required)

The form identifier

Returns:

The combined list of values

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Return a list of element names for the form with given id.

Switches:

-no_api (optional, boolean)

If provided, filter out form builder and ad_form API element names that start with the double underscore

Parameters:

id (required)

Author:

Peter Marklund

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Parameters:

id (required)

The form identifier

Returns:

the list of form errors

Partial Call Graph (max 5 caller/called nodes):

Testcases:

template_widget_file

Get properties of a form

Parameters:

id (required)

The ID of a form

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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. NB! This proc must always be called through "form get_values" or "template::form get_values", or it won't be able to find the variable.

Parameters:

id (required)

The form identifier

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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 (required)

The form identifier

Returns:

1 if preparing a form for an initial request; or 0 if repreparing a form that is returned to the user due to validation problems

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Return true if a submission in progress. The submission may or may not be valid.

Parameters:

id (required)

The form identifier

Returns:

1 if true or 0 if false

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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 (required)

The form identifier

Returns:

1 if id is the form identifier of a valid submission or 0 otherwise

Partial Call Graph (max 5 caller/called nodes):

Testcases:

template_widget_file

Render the HTML FORM tag along with a hidden element that identifies the form object.

Parameters:

id (required)

The form identifier

tag_attributes (required)

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Set the current section (fieldset) of the form. A form may be divided into any number of fieldsets to group related elements. Elements are tagged with the current fieldset properties as they are added to the form. A form style template may insert a divider in the form whenever the fieldset identifier changes.

Switches:

-fieldset (optional)

A list of name-value attribute pairs for the FIELDSET tag

-legendtext (optional)

The legend text

-legend (optional)

A list of name-value attribute pairs for the LEGEND tag

Parameters:

id (required)

The form identifier.

section (required)

The current fieldset identifier

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Set an error on a form element. Can be called from the -on_submit or -after_submit block of an ad_form. Will cause the form to no longer be considered valid, and thus the form will be redisplayed with the error message embedded, provided that 'break' is also called, so any code that redirects away from the form (e.g. in the after_submit block) isn't called either.

Parameters:

id (required)

The ID of the form

element (required)

The element that contains the error.

error (required)

The error message.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Set properties for a form

Parameters:

id (required)

The ID of an ATS form object.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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. NB! This proc must always be called through "form set_values" or "template::form set_values", or it won't be able to find the variable.

Parameters:

id (required)

The form identifier

array_ref (required)

The name of a local array variable whose keys correspond to element identifiers in the form

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Parameters:

id (required)

The form identifier

Returns:

the number of elements in the form identified by id

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Auto-generate the template for a form

Parameters:

id (required)

The form identifier

style (optional)

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.