template::element::create (public)

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

Defined in packages/acs-templating/tcl/element-procs.tcl

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
Source code:
    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 "" } {
        array set opts {sec_fieldset "" sec_legend "" sec_legendtext ""}
        if {[info exists form_properties(sec_fieldset)]}   {set opts(sec_fieldset)   $form_properties(sec_fieldset)}
        if {[info exists form_properties(sec_legend)]}     {set opts(sec_legend)     $form_properties(sec_legend)}
        if {[info exists form_properties(sec_legendtext)]} {set opts(sec_legendtext) $form_properties(sec_legendtext)}
    }

    if {[llength $args] > 0} {
        array set opts [::template::element::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" || $opts(widget) eq "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" || $opts(widget) eq "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)] } {

        if {[info exists opts(param)]} {
            ad_log warning "Outdated and deprecated form options detected,"  "The usage of opts(param) will be removed in versions past 5.10.1"
        }

        validate $form_id $element_id
    } elseif { [ns_queryget "__edit"] ne "" } {
        # 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]

        ad_log warning "This if-branch is insecure since it bypasses validation."  "the branch is deactivated rigjt now, and there is no know usage"  "of the __edit flag. If you still need it, uncomment the following line"  "and contact webmaster@openacs.org"
        error "Outdated and vulnerable code detected, contact webmaster@openacs.org"

        # 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 { $opts(widget) eq "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]
    }
XQL Not present:
Generic, PostgreSQL, Oracle
[ hide source ] | [ make this the default ]
Show another procedure: