template::form::create (public)

 template::form::create id [ args... ]

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

Initialize the data structures for a form.

Parameters:

id (required)

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.

Options:

-method

The standard METHOD attribute to specify in the HTML FORM tag at the beginning of the rendered form. Defaults to POST.

-html

A list of additional name-value attribute pairs to include in the HTML FORM tag at the beginning of the rendered form. Common use for this option is to set multipart form encoding by specifying "-html { enctype multipart/form-data }". Please note that to comply with newer security features, such as CSP, one should not specify JavaScript event handlers here, as they will be rendered inline.

-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.

-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.

-cancel_label

The label of the Cancel button, if cancel_url is supplied. Default is "Cancel".

-actions

A list of actions available on the form, which in practice means a 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 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.

-display_buttons

List of buttons to show when the form is in display mode. Equivalent to actions. If both actions and display_buttons are present, 'actions' is used. 'display_buttons' is deprecated.

-edit_buttons

List of buttons to show when the form is in edit mode. The value should be a list of lists, with the first element being the button label and the second element being the name. Defaults to { { "Ok" ok } }. The name of the button clicked can be retrieved using template::form::get_button.

-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.

-has_edit

Set to 1 to suppress the Edit button automatically added by the form builder. Use this if you include your own.

-elements

A block of element specifications.

-show_required_p

Should the form template show which elements are required. Use 1 or t for true, 0 or f for false. Defaults to true.

See Also:

• template::form::get_button
• template::form::get_action

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    set level [template::adp_level]

    # bump the form_count for widgets that use JavaScript to navigate through
    # the form (liberated from my Greenpeace work ages ago)

    incr ::ad_conn(form_count)

    # keep form properties and a list of the element items
    upvar #$level $id:elements elements $id:properties opts

    # ensure minimal defaults for form properties
    variable defaults
    array set opts $defaults

    template::util::get_opts $args

    set elements [list]

    # check whether this form is being submitted
    upvar #$level $id:submission submission

    if {$id eq "request"} {
        # request is the magic ID for the form holding query parameters
        set submission 1
    } else {
        # If there's a form:id argument, and it's the ID of this form,
        # we're being submitted
        set submission [string equal $id [ns_queryget form:id]]
    }

    set formbutton [get_button $id]

    # If the user hit a button named "cancel", redirect and about
    if { $submission && $formbutton eq "cancel" && [info exists opts(cancel_url)] && $opts(cancel_url) ne ""} {
        ad_returnredirect $opts(cancel_url)
        ad_script_abort
    }

    set formaction [get_action $id]
    # If we were in display mode, and a button was clicked, we should be in edit mode now
    if { $submission && [ns_queryget "form:mode"] eq "display" } {
        set opts(mode) "edit"
        set submission 0
    }

    # add elements specified at the time the form is created
    if { [info exists opts(elements)] } {

    # strip carriage returns
        regsub -all -- {\r} $opts(elements) {} element_data

        foreach element [split $element_data "\n"] {
            set element [string trim $element]
            if {$element eq {}} { continue }
            template::element create $id {*}$element
        }
    }

XQL Not present:

Generic, PostgreSQL, Oracle