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

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

Testcases:

template_widget_file

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

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.

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

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

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

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

Testcases:

No testcase defined.

Parameters:

id (required)

The form identifier

Returns:

the list of form errors

Testcases:

template_widget_file

Get properties of a form

Parameters:

id (required)

The ID of a form

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

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

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

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

Testcases:

template_widget_file

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

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.

Testcases:

No testcase defined.

Set properties for a form

Parameters:

id (required)

The ID of an ATS form object.

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

Testcases:

No testcase defined.

Parameters:

id (required)

The form identifier

Returns:

the number of elements in the form identified by id

Testcases:

No testcase defined.