export_vars (public)

 export_vars [ -sign ] [ -form ] [ -url ] [ -quotehtml ] \
    [ -entire_form ] [ -no_empty ] [ -base base ] [ -no_base_encode ] \
    [ -anchor anchor ] [ -exclude exclude ] [ -override override ] \
    [ 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 usage: 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 (boolean) (optional)
Sign all variables.
-form (boolean) (optional)
Export in form format. You can't specify both URL and form format.
-url (boolean) (optional)
Export in URL format. This is the default.
-quotehtml (boolean) (optional)
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 (boolean) (optional)
Export the entire form from the GET query string or the POST.
-no_empty (boolean) (optional)
-base (optional)
-no_base_encode (boolean) (optional)
-anchor (optional)
-exclude (optional)
-override (optional)
Parameters:
vars (optional)
Options:
-no_empty
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
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
Decides whether argument passed as base option will be encoded by ad_urlencode_url proc
Author:
Lars Pind <lars@pinds.com>
Created:
December 7, 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_subsite_test_email_confirmation acs_subsite_test_email_confirmation (test acs-subsite) export_vars export_vars test_acs_subsite_test_email_confirmation->export_vars test_create_form_with_form_instance create_form_with_form_instance (test xowiki) test_create_form_with_form_instance->export_vars test_create_workflow_with_instance create_workflow_with_instance (test xowf) test_create_workflow_with_instance->export_vars test_export_vars export_vars (test acs-tcl) test_export_vars->export_vars test_form_validate form_validate (test xowiki) test_form_validate->export_vars Class ::Generic::Form Class ::Generic::Form (public) Class ::Generic::Form->export_vars Class ::Generic::List Class ::Generic::List (public) Class ::Generic::List->export_vars Class ::xo::Context Class ::xo::Context (public) Class ::xo::Context->export_vars Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->export_vars Class ::xowiki::includelet::child-resources Class ::xowiki::includelet::child-resources (public) Class ::xowiki::includelet::child-resources->export_vars

Testcases:
acs_subsite_test_email_confirmation, export_vars, postman_echo, create_workflow_with_instance, package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve, create_form_with_form_instance, form_validate
[ show source ]
Show another procedure: