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