• Publicity: Public Only All

element-procs.tcl

Form element procedures for the OpenACS Templating System

Location:
packages/acs-templating/tcl/element-procs.tcl
Authors:
Karl Goldstein <karlg@arsdigita.com>
Stanislav Freidin <sfreidin@arsdigita.com>
CVS Identification:
$Id: element-procs.tcl,v 1.40 2024/10/01 12:44:32 gustafn Exp $

Procedures in this file

Detailed information

element (public, deprecated)

 element command form_id element_id [ args... ]
Deprecated. Invoking this procedure generates a warning.

element is really template::element although when in the "template" namespace you may omit the template:: qualifier. See the template::form API for creating the form element container. DEPRECATED: please use the properly namespaced api

Parameters:
command (required)
form_id (required)
element_id (required)
See Also:

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

Testcases:
No testcase defined.

template::element (public)

 template::element command form_id element_id [ args... ]

Manage elements of form objects.

see the individual commands for further information.

Parameters:
command (required)
one of create, error_p, exists, get_property, get_value, get_values, querygetall, set_error, set_properties, set_value
form_id (required)
string identifying the form
element_id (required)
string identifying the element
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_template_widget_file template_widget_file (test acs-templating) template::element template::element test_template_widget_file->template::element ad_form ad_form (public) ad_form->template::element attribute::add_form_elements attribute::add_form_elements (public) attribute::add_form_elements->template::element forums::form::forum forums::form::forum (public) forums::form::forum->template::element forums::form::forward_message forums::form::forward_message (public) forums::form::forward_message->template::element forums::form::message forums::form::message (public) forums::form::message->template::element

Testcases:
template_widget_file

template::element::create (public)

 template::element::create form_id element_id [ args... ]

Append an element to a form object. If a submission is in progress, values for the element are prepared and validated.

Parameters:
form_id (required)
The identifier of the form to which the element is to be added. The form must have been previously created with a form create statement.
element_id (required)
A keyword identifier for the element that is unique in the context of the form.
Options:
-widget
The name of an input widget for the element. Valid widgets must have a rendering procedure defined in the template::widget namespace.
-datatype
The name of a datatype for the element values. Valid datatypes must have a validation procedure defined in the template::data::validate namespace.
-label
The label for the form element.
-html
A list of name-value attribute pairs to include in the HTML tag for widget. Typically used for additional formatting options, such as cols or rows, or for JavaScript handlers.
-maxlength
The maximum allowable length in bytes. Will be checked using 'string bytelength'. Will also cause 'input' widgets (text, integer, etc.) to get a maxlength="..." attribute.
-options
A list of options for select lists and button groups (check boxes or radio buttons). The list contains two-element lists in the form { {label value} {label value} {label value} ...}
-fieldset
A list of name-value attribute pairs to include in the HTML tag for checkboxes and radio FIELDSET.
-legend
A list of name-value attribute pairs to include in the HTML tag for checkboxes and radio LEGEND.
-legendtext
A text for the LEGEND tag to include in the checkboxes and radio FIELDSET block
-value
The default value of the element
-values
The default values of the element, where multiple values are allowed (checkbox groups and multiselect widgets)
-validate
A list of custom validation blocks in the form {name { script } { message } name { script } { message } ...} where name is a unique identifier for the validation step, expression is a block to Tcl code (script) that should set the result to 1 or 0, and message is to be displayed to the user when the validation step fails, that is, if the expression evaluates to 0. Use the special variable $value to refer to the value entered by the user in that field. Note that e.g. in ad_form, all blocks are substituted, therefore, the script might require escaping.
-sign
Specify for a hidden widget that its value should be signed
-help_text
Text displayed with the element
-help
Display helpful hints (date widget only?)
-optional
A flag indicating that no value is required for this element. If a default value is specified, the default is used instead.
-mode
Valid values are 'display', 'edit', and the empty string. If set to 'display', the element will render as static HTML which doesn't allow editing of the value, instead of the HTML form element (e.g. <input>) which would otherwise get used. If set to 'edit', the element is as normal, allowing the user to edit the contents. If set to the empty string or not specified at all, the form's 'mode' setting is used instead.
-nospell
A flag indicating that no spell-checking should be performed on this element. This overrides the 'SpellcheckFormWidgets' parameter.
-noquote
A flag indicating that no value should not be quoted in a form. In addition, the nonquoted inform field is not transmitted as a hidden field (which can be attacked via noquote). Currently only supported by the "inform" widget type.
-before_html
A chunk of HTML displayed immediately before the rendered element.
-after_html
A chunk of HTML displayed immediately after the rendered element.
-display_value
Alternative value used when the element is in display mode. If specified, this value is used when the mode is set to 'display', instead of asking the element widget to render itself in display mode.
-multiple
A flag indicating that more than one value is expected from the input element
-format
Many form elements allow one to specify a format, e.g. a way the element should be displayed or interpret its value. Refer to the specific widgets for the actual behavior.
-section
Specify to which form section this element belongs
-htmlarea_p
Only relevant for textarea kind of elements, tells if the element is supposed to be rendered as a richtext editor or not.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_template_widget_file template_widget_file (test acs-templating) template::element::create template::element::create test_template_widget_file->template::element::create ad_log ad_log (public) template::element::create->ad_log ad_sign ad_sign (public) template::element::create->ad_sign template::adp_level template::adp_level (public) template::element::create->template::adp_level template::element::copy_value_to_values_if_defined template::element::copy_value_to_values_if_defined (private) template::element::create->template::element::copy_value_to_values_if_defined template::element::get_opts template::element::get_opts (private) template::element::create->template::element::get_opts template::element::set_properties template::element::set_properties (public) template::element::set_properties->template::element::create template::request::set_param template::request::set_param (public) template::request::set_param->template::element::create

Testcases:
template_widget_file

template::element::error_p (public)

 template::element::error_p form_id element_id

Return true if the named element has an error set. Helpful for client code that wants to avoid overwriting an initial error message.

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element with which the error message should be associated in the form template.

Partial Call Graph (max 5 caller/called nodes):
%3 template::adp_level template::adp_level (public) template::element::error_p template::element::error_p template::element::error_p->template::adp_level

Testcases:
No testcase defined.

template::element::exists (public)

 template::element::exists form_id element_id

Determine if an element exists in a specified form

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element within the form.
Returns:
1 if the element exists in the form, or 0 otherwise

Partial Call Graph (max 5 caller/called nodes):
%3 ad_form ad_form (public) template::element::exists template::element::exists ad_form->template::element::exists template::element::set_properties template::element::set_properties (public) template::element::set_properties->template::element::exists template::list::prepare_filter_form template::list::prepare_filter_form (private) template::list::prepare_filter_form->template::element::exists template::wizard::submit template::wizard::submit (public) template::wizard::submit->template::element::exists template::adp_level template::adp_level (public) template::element::exists->template::adp_level

Testcases:
No testcase defined.

template::element::get_property (public)

 template::element::get_property form_id element_id property

Retrieves the specified property of the element, such as value, datatype, widget, etc.

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
property (required)
The property to be retrieved
Returns:
The value of the property, or "" if the property does not exist
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 template::element::get_reference template::element::get_reference (private) template::element::get_property template::element::get_property template::element::get_property->template::element::get_reference

Testcases:
No testcase defined.

template::element::get_value (public)

 template::element::get_value form_id element_id

Retrieves the current value of an element. Typically used following a valid form submission to retrieve the submitted value.

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
Returns:
The current value of the element.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 package_instantiate_object package_instantiate_object (public) template::element::get_value template::element::get_value package_instantiate_object->template::element::get_value packages/acs-subsite/www/admin/users/new.tcl packages/acs-subsite/ www/admin/users/new.tcl packages/acs-subsite/www/admin/users/new.tcl->template::element::get_value packages/photo-album/www/album-add.tcl packages/photo-album/ www/album-add.tcl packages/photo-album/www/album-add.tcl->template::element::get_value packages/photo-album/www/album-edit.tcl packages/photo-album/ www/album-edit.tcl packages/photo-album/www/album-edit.tcl->template::element::get_value packages/photo-album/www/album-move.tcl packages/photo-album/ www/album-move.tcl packages/photo-album/www/album-move.tcl->template::element::get_value template::element::get_reference template::element::get_reference (private) template::element::get_value->template::element::get_reference

Testcases:
No testcase defined.

template::element::get_values (public)

 template::element::get_values form_id element_id

Retrieves the list current values for an element. Typically used following a valid form submission where multiple values may have been submitted for a single element (i.e. for a checkbox group or multiple select box).

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
Returns:
A list of current values for the element.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 template::request::get_param template::request::get_param (public) template::element::get_values template::element::get_values template::request::get_param->template::element::get_values template::element::get_reference template::element::get_reference (private) template::element::get_values->template::element::get_reference

Testcases:
No testcase defined.

template::element::querygetall (public)

 template::element::querygetall element_ref

Get all values for an element, performing any transformation defined for the datatype.

Parameters:
element_ref (required)

Partial Call Graph (max 5 caller/called nodes):
%3 template::element::create template::element::create (public) template::element::querygetall template::element::querygetall template::element::create->template::element::querygetall template::element::validate template::element::validate (private) template::element::validate->template::element::querygetall template::data::transform::spellcheck template::data::transform::spellcheck (public) template::element::querygetall->template::data::transform::spellcheck template::util::spellcheck::spellcheck_properties template::util::spellcheck::spellcheck_properties (public) template::element::querygetall->template::util::spellcheck::spellcheck_properties

Testcases:
No testcase defined.

template::element::set_error (public)

 template::element::set_error form_id element_id message

Manually set an error message for an element. This may be used to implement validation filters that involve more than one form element ("Sorry, blue is not available for the model you selected, please choose another color.")

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element with which the error message should be associated in the form template.
message (required)
The text of the error message.

Partial Call Graph (max 5 caller/called nodes):
%3 test_template_widget_file template_widget_file (test acs-templating) template::element::set_error template::element::set_error test_template_widget_file->template::element::set_error template::adp_level template::adp_level (public) template::element::set_error->template::adp_level template::data::transform::category template::data::transform::category (public) template::data::transform::category->template::element::set_error template::data::transform::party_search template::data::transform::party_search (private) template::data::transform::party_search->template::element::set_error template::data::transform::search template::data::transform::search (public) template::data::transform::search->template::element::set_error template::data::transform::spellcheck template::data::transform::spellcheck (public) template::data::transform::spellcheck->template::element::set_error

Testcases:
template_widget_file

template::element::set_properties (public)

 template::element::set_properties form_id element_id [ args... ]

Modify properties of an existing element. The same options may be used as with the create command. Most commonly used to set the default value for an element when a form page is initially requested.

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 template::data::transform::spellcheck template::data::transform::spellcheck (public) template::element::set_properties template::element::set_properties template::data::transform::spellcheck->template::element::set_properties ad_sign ad_sign (public) template::element::set_properties->ad_sign template::element::copy_value_to_values_if_defined template::element::copy_value_to_values_if_defined (private) template::element::set_properties->template::element::copy_value_to_values_if_defined template::element::create template::element::create (public) template::element::set_properties->template::element::create template::element::exists template::element::exists (public) template::element::set_properties->template::element::exists template::element::get_reference template::element::get_reference (private) template::element::set_properties->template::element::get_reference

Testcases:
No testcase defined.

template::element::set_value (public)

 template::element::set_value form_id element_id value

Sets the value of an element

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
value (required)
The value to apply

Partial Call Graph (max 5 caller/called nodes):
%3 ad_form ad_form (public) template::element::set_value template::element::set_value ad_form->template::element::set_value template::element::get_reference template::element::get_reference (private) template::element::set_value->template::element::get_reference

Testcases:
No testcase defined.

template::element::set_values (public)

 template::element::set_values form_id element_id values

Sets the list of values of an element

Parameters:
form_id (required)
The identifier of the form containing the element.
element_id (required)
The unique identifier of the element.
values (required)
The list of values to apply

Partial Call Graph (max 5 caller/called nodes):
%3 template::element::get_reference template::element::get_reference (private) template::element::set_values template::element::set_values template::element::set_values->template::element::get_reference

Testcases:
No testcase defined.
[ show source ]