export_form_vars,
- export_url_vars
- and all their friends.
+
+ 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 }]
- Example usage: [export_vars -form { 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}].
- 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.
+ 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.
+ 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
+ The two variable specs, vars and
+ override both look the same: They take a list of
variable specs. Examples of variable specs are:
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.
+ 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: + Right after the name, you may specify a colon and some flags, + separated by commas. Valid flags are:
: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.
-
+
+ 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.
+
: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.
+
+ 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. +
exclude simply takes a list of names of variables that you don't
- want exported, even though they're specified in vars.
+ 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:
+ 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].
+ 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.
+ [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.
+ If the variable name contains a colon (:), that colon must be
+ escaped with a backslash, so for example "form:id" becomes
+ "form\:id". Sorry.
@param sign Sign all variables.
@param url Export in URL format. This is the default.
- @param form Export in form format. You can't specify both URL and form format.
+ @param form Export in form format. You can't specify both URL and
+ form format.
- @param quotehtml 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.
+ @param quotehtml 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.
- @param entire_form Export the entire form from the GET query string or the POST.
+ @param entire_form Export the entire form from the GET query
+ string or the POST.
- @option 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.
+ @option 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.
- @option base The base URL to make a link to. This will be prepended to the query string
- along with a question mark (?), if the query is nonempty. So the returned
- string can be used directly in a link. This is only relevant to URL export.
+ @option base The base URL to make a link to. This will be
+ prepended to the query string along with a question mark (?), if
+ the query is nonempty. So the returned string can be used directly
+ in a link. This is only relevant to URL export.
- @option no_base_encode Decides whether argument passed as base option will be
- encoded by ad_urlencode_url proc
+ @option no_base_encode Decides whether argument passed as
+ base option will be encoded by
+ ad_urlencode_url proc
@author Lars Pind (lars@pinds.com)
@creation-date December 7, 2000