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.37.2.17 -r1.37.2.18 --- openacs-4/packages/acs-templating/tcl/element-procs.tcl 30 Aug 2022 08:50:37 -0000 1.37.2.17 +++ openacs-4/packages/acs-templating/tcl/element-procs.tcl 30 Aug 2022 09:22:53 -0000 1.37.2.18 @@ -179,111 +179,131 @@ 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. + 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 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 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. + 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 fieldset A list of name-value attribute pairs to include in - the HTML tag for checkboxes and radio FIELDSET. + @option fieldset A list of name-value attribute pairs to include + in the HTML tag for checkboxes and radio + FIELDSET. @option legend A list of name-value attribute pairs to include in - the HTML tag for checkboxes and radio LEGEND. + the HTML tag for checkboxes and radio + LEGEND. - @option legendtext A text for the LEGEND tag to include in - the checkboxes and radio FIELDSET block + @option legendtext A text for the LEGEND tag to include in the + checkboxes and radio FIELDSET block @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 values The default values of the element, where multiple + values are allowed (checkbox groups and + multiselect widgets) @option 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. + {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. - @option sign specify for a hidden widget that its value should be - signed + @option sign Specify for a hidden widget that its value should be + signed @option help_text Text displayed with the element @option help Display helpful hints (date widget only?) - @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 optional A flag indicating that no value is required for + this element. If a default value is + specified, the default is used instead. - @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 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 nospell A flag indicating that no spell-checking should be performed on - this element. This overrides the 'SpellcheckFormWidgets' parameter. + @option nospell A flag indicating that no spell-checking should be + performed on this element. This overrides + the 'SpellcheckFormWidgets' parameter. - @option 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. + @option 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. @option before_html A chunk of HTML displayed immediately before the rendered element. @option after_html A chunk of HTML displayed immediately after the rendered element. - @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. + @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. - @option multiple A flag indicating that more than one value is expected - from the input element + @option multiple A flag indicating that more than one value is + expected from the input element @option format Many form elements allow 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. + e.g. a way the element should be displayed + or interpret its value. Refer to the + specific widgets for the actual behavior. @option section Specify to which form section this element belongs @option htmlarea_p Only relevant for textarea kind of elements, - tells if the element is supposed to be - rendered as a richtext editor or not. + tells if the element is supposed to be + rendered as a richtext editor or not. @see template::widget @see template::data::validate @@ -808,9 +828,9 @@ @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element within the form. @param tag_attributes A name-value list of addditional HTML - attributes to include in the tag, such as JavaScript - handlers or special formatting (i.e. ROWS and COLS - for a TEXTAREA). + attributes to include in the tag, such as + JavaScript handlers or special formatting + (i.e. ROWS and COLS for a TEXTAREA). @return A string containing the HTML for an INPUT, SELECT or TEXTAREA form element. @@ -845,9 +865,9 @@ @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element within the form. @param tag_attributes A name-value list of addditional HTML - attributes to include in the INPUT tags for each - radio button or checkbox, such as JavaScript - handlers or special formatting. + attributes to include in the INPUT tags for + each radio button or checkbox, such as + JavaScript handlers or special formatting. } { get_reference