export_vars (public)

 export_vars [ -sign ] [ -form ] [ -url ] [ -quotehtml ] \
    [ -entire_form ] [ -no_empty ] [ -base base ] [ -no_base_encode ] \
    [ -anchor anchor ] [ -exclude exclude ] [ -override override ] \
    [ -set set ] [ -formvars formvars ] [ vars ]

Defined in packages/acs-tcl/tcl/utilities-procs.tcl

Exports variables either as a URL or in the form of hidden form variables. The result is properly urlencoded, unless flags prohibit this.

Example usages:

    set html [export_vars -form { foo bar baz }]
    set url [export_vars { foo bar baz }]

This will export the three variables foo, bar and baz as hidden HTML form fields. It does exactly the same as [export_vars -form {foo bar baz}].

Example usage:

    export_vars -sign -override {{foo "new value"}} -exclude { bar } { foo bar baz }

This will export a variable named foo with the value "new value" and a variable named baz with the value of baz in the caller's environment. Since we've specified that bar should be excluded, bar won't get exported even though it's specified in the last argument. Additionally, even though foo is specified also in the last argument, the value we use is the one given in the override argument. Finally, both variables are signed, because we specified the -sign switch.

You can specify variables with three different precedences, namely override, exclude or vars. If a variable is present in override, that's what'll get exported, no matter what. If a variable is in exclude and not in override, then it will not get output. However, if it is in vars and not in either of override or exclude, then it'll get output. In other words, we check override, exclude and vars in that order of precedence.

The two variable specs, vars and override both look the same: They take a list of variable specs. Examples of variable specs are:

• foo
• foo:multiple,sign
• {foo "the value"}
• {foo {[my_function arg]}}
• {foo:array,sign {[array get my_array]}}

In general, there's one or two elements. If there are two, the second element is the value we should use. If one, we pull the value from the variable of the same name in the caller's environment. Note that when you specify the value directly here, we call the Tcl command subst on it, so backslashes, square brackets and variables will get substituted correctly. Therefore, make sure you use curly braces to surround this instead of the [list] command; otherwise the contents will get substituted twice, and you'll be in trouble.

Right after the name, you may specify a colon and some flags, separated by commas. Valid flags are:

multiple

Treat the value as a list and output each element separately.

array

The value is an array and should be exported in a way compliant with the :array flag of ad_page_contract, which means that each entry will get output as name.key=value.

If you don't specify a value directly, but want it pulled out of the Tcl environment, then you don't need to specify :array. If you do, and the variable is in fact not an array, an error will be thrown.

sign

Sign this variable. This goes hand-in-hand with the :verify flag of ad_page_contract and makes sure that the value isn't tampered with on the client side. The -sign switch to export_vars, is a short-hand for specifying the :sign switch on every variable.

For example, one can use "user_id:sign(max_age=60)" in export_vars to let the exported variable after 60 seconds. Other potential arguments for sign are "user" or "csrf" to bind the signature to a user or to the CSRF token.

The argument exclude simply takes a list of names of variables that you don't want exported, even though they're specified in vars.

Intended use: A page may have a set of variables that it cares about. You can store this in a variable once and pass that to export_vars like this:

set my_vars { user_id sort_by filter_by }
... [export_vars $my_vars] ...

Then, say one of them contains a column to filter on. When you want to clear that column, you can say [export_vars -exclude { filter_by } $my_vars].

Similarly, if you want to change the sort order, you can say [export_vars -override { { sort_by $column } } $my_vars], and sorting will be done according to the new value of column.

If the variable name contains a colon (:), that colon must be escaped with a backslash, so for example "form:id" becomes "form\:id". Sorry.

Switches:

-sign (optional, boolean)

Sign all variables.

-form (optional, boolean)

Export in form format. You can't specify both URL and form format.

-url (optional, boolean)

Export in URL format. This is the default.

-quotehtml (optional, boolean)

HTML quote the entire resulting string. This is an interim solution while we're waiting for the templating system to do the quoting for us.

-entire_form (optional, boolean)

Export the entire form from the GET query string or the POST.

-no_empty (optional, boolean)

If specified, variables with an empty string value will be suppressed from being exported. This avoids cluttering up the URLs with lots of unnecessary variables.

-base (optional)

The base URL to make a link to. The provided value should be a plain value (i.e. urldecoded). In case the provided value is urlencoded, use the flag "-no_base_encode". The value of this parameter will be prepended to the query string along with a question mark (?), if the query is nonempty. The returned string can be used directly in a link (when output is in URL format).

-no_base_encode (optional, boolean)

Decides whether argument passed as base option will be encoded by ad_urlencode_url proc

-anchor (optional)

fragment component that will be preceded by a hash (#) in the result URL

-exclude (optional)

list of variables that will not be exported

-override (optional)

variable specs, overriding the specs in 'vars'

-set (optional)

an ns_set that we want to export together with our variables. It has no effect when also the '-entire_form' flag is specified and will otherwise behave as if the current request form data was the supplied ns_set.

-formvars (optional)

a list of parameters that will be looked up into the current request and exported. Won't have any effect if '-entire_form' or '-set' are specified and will otherwise behave as if the current request form data was a subset of the whole form containing only the selected variables.

Parameters:

vars (optional)

variable specs for export

Author:

Lars Pind <lars@pinds.com>

Created:

December 7, 2000

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

Testcases:

acs_subsite_test_email_confirmation, export_vars, postman_echo, util_http_post_vars, create_workflow_with_instance, package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve, create_form_with_form_instance, form_validate