# Form element procedures for the OpenACS Templating System # # Copyright (C) 1999-2000 ArsDigita Corporation # Authors: Karl Goldstein (karlg@arsdigita.com) # Stanislav Freidin (sfreidin@arsdigita.com) # # $Id: element-procs.tcl,v 1.30 2012/07/28 04:31:20 torbenb Exp $ # # This is free software distributed under the terms of the GNU Public # License. Full text of the license is available from the GNU Project: # http://www.fsf.org/copyleft/gpl.html namespace eval template {} namespace eval template::element {} ad_proc -public element { command form_id element_id args } { 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. @see template::element @see template::form } - ad_proc -public template::element { command form_id element_id args } { Manage elements of form objects.
see the individual commands for further information. @param command one of create, error_p, exists, get_property, get_value, get_values, querygetall, set_error, set_properties, set_value @param form_id string identifying the form @param element_id string identifying the element @see template::element::create @see template::element::error_p @see template::element::exists @see template::element::get_property @see template::element::get_value @see template::element::get_values @see template::element::querygetall @see template::element::set_error @see template::element::set_properties @see template::element::set_value @see template::form } { eval template::element::$command $form_id $element_id $args } ad_proc -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. @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. @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 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 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 legend A list of name-value attribute pairs to include in 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 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 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, 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. @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 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 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. @see template::widget @see template::data::validate @see template::form::create @see template::form::section } { set level [template::adp_level] # add the element to the element list upvar #$level $form_id:elements elements $form_id:properties form_properties if { ! [info exists elements] } { error "Form $form_id does not exist" } lappend elements $form_id:$element_id lappend form_properties(element_names) $element_id # add the reference to the elements lookup array for the form upvar #$level $form_id:$element_id opts if {[info exists opts]} { error "Element '$element_id' already exists in form '$form_id'." } set opts(id) $element_id set opts(form_id) $form_id # ensure minimal defaults for element parameters variable defaults array set opts $defaults # By default, the form/edit mode is set to the empty string # Can be set to something else if you want set opts(mode) {} # set the form section set opts(section) $form_properties(section) if { $opts(section) ne "" } { set opts(sec_fieldset) $form_properties(sec_fieldset) set opts(sec_legend) $form_properties(sec_legend) set opts(sec_legendtext) $form_properties(sec_legendtext) } template::util::get_opts $args # set a name if none specified if { ! [info exists opts(name)] } { set opts(name) $opts(id) } # set a label if none specified if { ! [info exists opts(label)] } { set opts(label) $element_id } # If the widget is a submit widget, remember it # All submit widgets are optional if { $opts(widget) eq "submit" || \ [string equal $opts(widget) "button"] } { set form_properties(has_submit) 1 set opts(optional) 1 if { ! [info exists opts(value)] } { set opts(value) $opts(label) } if { ! [info exists opts(label)] } { set opts(label) $opts(value) } } # If the widget is a checkbox or radio widget, set attributes if { $opts(widget) eq "radio" || \ [string equal $opts(widget) "checkbox"] } { # If there's no legend text, no point to generate the fieldset if { ![info exists opts(legendtext)] } { if { [info exists opts(legend)] || [info exists opts(fieldset)] } { ns_log Warning "template::element::create (form: $form_id, element: $opts(name)): you set fieldset and/or legend properties but not the legendtext one. You must provide text for the legend tag." } } else { # set fieldset attributes if { ![info exists opts(fieldset)] } { set opts(fieldset) {} } array set fs_attributes $opts(fieldset) set fs_options "" if {![info exists fs_attributes(class)]} { append fs_options " class=\"form-fieldset\"" } foreach name [array names fs_attributes] { if {$fs_attributes($name) eq {}} { append fs_options " $name" } else { append fs_options " $name=\"$fs_attributes($name)\"" } } set opts(fieldset) $fs_options # set legend attributes if { ![info exists opts(legend)] } { set opts(legend) {} } array set lg_attributes $opts(legend) set lg_options "" foreach name [array names lg_attributes] { if {$lg_attributes($name) eq {}} { append lg_options " $name" } else { append lg_options " $name=\"$lg_attributes($name)\"" } } set opts(legend) $lg_options } } # Remember that the element has not been rendered yet set opts(is_rendered) f copy_value_to_values_if_defined # check for submission if { [template::form is_submission $form_id] || [info exists opts(param)] } { validate $form_id $element_id } elseif { ![empty_string_p [ns_queryget "__edit"]] } { # If the magic __edit button was hit, try to get values from the form still # but don't do any validation set opts(values) [querygetall opts] # be careful not to clobber a default value if one has been specified if { [llength $opts(values)] || ! [info exists opts(value)] } { set opts(value) [lindex $opts(values) 0] } } if { [string equal $opts(widget) "hidden"] && [info exists opts(sign)] && $opts(sign) } { if {[info exists opts(value)] } { set val $opts(value) } else { set val {} } template::element::create $opts(form_id) $opts(id):sig \ -datatype text \ -widget hidden \ -section $opts(section) \ -value [ad_sign $val] } } ad_proc -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. @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element. @see template::element::create } { get_reference # create a reference to opts as expected by get_opts upvar 0 element opts template::util::get_opts $args if { [string equal $opts(widget) "hidden"] && [info exists opts(sign)] && $opts(sign) && [info exists opts(value)] } { if { [template::element::exists $form_id $element_id:sig] } { template::element::set_properties $form_id $element_id:sig \ -value [ad_sign $opts(value)] } else { template::element::create $form_id $element_id:sig \ -datatype text \ -widget hidden \ -value [ad_sign $opts(value)] } } copy_value_to_values_if_defined } ad_proc -public template::element::set_value { form_id element_id value } { Sets the value of an element @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element. @param value The value to apply } { get_reference set element(value) $value set element(values) [list $value] } ad_proc -public template::element::set_values { form_id element_id values } { Sets the list of values of an element @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element. @param values The list of values to apply } { get_reference set element(values) $values } ad_proc -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. @param form_id The identifier of the form containing the element. @param element_id The unique identifier of the element. @return The current value of the element. @see template::element::get_values } { get_reference if { [info exists element(value)] } { regsub {