Index: openacs-4/packages/acs-templating/tcl/element-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/element-procs.tcl,v
diff -u -r1.9.2.9 -r1.9.2.10
--- openacs-4/packages/acs-templating/tcl/element-procs.tcl 25 Apr 2003 08:45:08 -0000 1.9.2.9
+++ openacs-4/packages/acs-templating/tcl/element-procs.tcl 10 May 2003 16:08:15 -0000 1.9.2.10
@@ -47,68 +47,78 @@
Append an element to a form object. If a submission is in progress,
values for the element are prepared and validated.
- @param form_id 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.
+ @param form_id 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.
+ @param element_id A keyword identifier for the element that is unique
+ in the context of the form.
- @param element_id A keyword identifier for the element that is unique
- in the context of the form.
+ @option widget The name of an input widget for the element. Valid
+ widgets must have a rendering procedure defined in
+ the template::widget namespace.
+ @option datatype The name of a datatype for the element values. Valid
+ datatypes must have a validation procedure defined in
+ the template::data::validate namespace.
- @option widget The name of an input widget for the element. Valid
- widgets must have a rendering procedure defined in
- the template::widget namespace.
-
- @option datatype The name of a datatype for the element values. Valid
- datatypes must have a validation procedure defined in
- the template::data::validate namespace.
-
- @option label The label for the form element.
+ @option label The label for the form element.
- @option section The section name for the element.
+ @option section The section name for the element.
- @option 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.
+ @option 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.
+ @option 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.
- @option 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.
+ @option 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} ...}
- @option 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} ...}
+ @option value The default value of the element
+ @option values The default values of the element, where multiple values
+ are allowed (checkbox groups and multiselect widgets)
- @option value The default value of the element
+ @option validate A list of custom validation blocks in the form
+ { name { expression } { message } \
+ name { expression } { message } ...}
+ where name is a unique identifier for the validation
+ step, expression is a block to Tcl code that evaluates to
+ 1 or 0, and message is to be displayed to the user when
+ the validation step fails.
+ @option sign specify for a hidden widget that its value should be
+ signed
- @option values The default values of the element, where multiple values
- are allowed (checkbox groups and multiselect widgets)
+ @option help_text Text displayed with the element
+ @option help Display helpful hints (date widget only?)
- @option validate A list of custom validation blocks in the form
- { name { expression } { message } \
- name { expression } { message } ...}
- where name is a unique identifier for the validation
- step, expression is a block to Tcl code that evaluates to
- 1 or 0, and message is to be displayed to the user when
- the validation step fails.
+ @option optional A flag indicating that no value is required for this
+ element. If a default value is specified, the default
+ is used instead.
- @option sign specify for a hidden widget that its value should be
- signed
+ @option 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.
- @option help_text Text displayed with the element
+ @option before_html A chunk of HTML displayed immediately before the rendered element.
- @option help Display helpful hints (date widget only?)
+ @option after_html A chunk of HTML displayed immediately after the rendered element.
- @option optional A flag indicating that no value is required for this
- element. If a default value is specified, the default
- is used instead.
+ @option 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.
@see template::widget
@see template::data::validate
Index: openacs-4/packages/acs-templating/tcl/form-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/form-procs.tcl,v
diff -u -r1.7.2.4 -r1.7.2.5
--- openacs-4/packages/acs-templating/tcl/form-procs.tcl 7 Mar 2003 13:48:06 -0000 1.7.2.4
+++ openacs-4/packages/acs-templating/tcl/form-procs.tcl 10 May 2003 16:08:15 -0000 1.7.2.5
@@ -49,20 +49,63 @@
ad_proc -public template::form::create { id args } {
Initialize the data structures for a form.
- @param 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.
+ @param 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.
- @option method The standard METHOD attribute to specify in the HTML FORM
- tag at the beginning of the rendered form. Defaults to POST.
+ @option method The standard METHOD attribute to specify in the HTML FORM
+ tag at the beginning of the rendered form. Defaults to POST.
- @option 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() }"
+ @option 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() }"
+
+ @option 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.
+
+ @option 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.
+
+ @option cancel_label The label of the Cancel button, if cancel_url is supplied.
+ Default is "Cancel".
+
+ @option display_buttons 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 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.
- @option elements A block of element specifications.
+ @option edit_buttons 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 name of the form element. Defaults to
+ { { "Ok" ok } }. The name of the button clicked can be retrieved using
+ template::form::get_button.
+
+ @option actions A list of actions available on the form. Equivalent to, and
+ overrides display_buttons.
+
+ @option 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.
+
+ @option has_edit Set to 1 to suppress the Edit button automatically added by the
+ form builder. Use this if you include your own.
+
+ @option elements A block of element specifications.
+
+ @see template::form::get_button
+ @see template::form::get_action
+
} {
set level [template::adp_level]
@@ -177,7 +220,8 @@
}
ad_proc -public template::form::get_action { id } {
- Find out which action is in progress
+ Find out which action is in progress. This is the name of the button
+ which was clicked when the form was in display mode.
@param id The ID of an ATS form object.
@return the name of the action in progress