CML Reference Guide
Chapter 4.17: User, Conference, Item, Site Variables |
[TOP]
[UP]
[PREV]
[NEXT]
|
The "regular" CML variables (e.g., "set var xyz"
or "$(var)") are ephemeral: once the dedicated swebs
server has exited, the values of those variables are lost.
CML also provides a set of variables that are persistent across
sessions, and tied to a particular user, conference, item, or
to the site as a whole.
Such variables may contain any amount of text, including newlines.
They provide a convenient way to extend a Caucus interface, and
to customize how the interface appears to a particular user or
in a particular conference or item.
Note that evaluating a variable is a fairly fast process. (All
variables for a particular user, conference, item or site, are loaded
when needed, and cached.) Setting a variable is much slower,
since the values must be written to disk.
- $user_var(user vname)
-
Evaluates to the value of userid user's variable called
vname.
- $set_user_var(user vname value)
-
Sets userid user's variable vname to value.
- $clear_user_var()
-
Clears the user variable cache.
- $list_user_var(user str)
-
Evaluates to a blank-separated list of user's variable
names that begin with str.
If str is not supplied, lists all of user's variables.
- $conf_var(cnum vname)
-
Evaluates to the value of conference cnum's variable called
vname.
- $set_conf_var(cnum vname value)
-
Sets conference cnum's variable vname to value.
- $clear_conf_var()
-
Clears the conference variable cache.
- $list_conf_var(cnum str)
-
Evaluates to a blank-separated list of conference cnum's variable
names that begin with str.
If str is not supplied, lists all of cnum's variables.
- $item_var(cnum inum vname)
-
Evaluates to the value of conference cnum, item inum's
variable called vname.
- $set_item_var(cnum inum vname value)
-
Sets conference cnum, item inum's variable vname
to value.
- $clear_item_var()
-
Clears the item variable cache.
- $list_item_var(cnum inum str)
-
Evaluates to a blank-separated list of conference cnum,
item inum's variable names that begin with str.
If str is not supplied, lists all of item inum's variables.
- $site_var(vname)
-
Evaluates to the value of the site variable called
vname.
Site variables are "global" across an entire installation of Caucus
and are available to all users.
- $set_site_var(vname value)
-
Sets site variable vname to value.
- $clear_site_var()
-
Clears the site variable cache.
- $list_site_var(str)
-
Evaluates to a blank-separated list of the site variable
names that begin with str.
If str is not supplied, lists all of the site variables.
It is important to remember that all of these variables are
cached for each user. This makes getting the
value of a variable very fast; but it also means that if
someone else changes a variable, your copy of the variable
may be out of date.
In most cases this doesn't matter.
But if you need to be sure that the value of a variable is
up-to-date, call the appropriate $clear_... function immediately
before using the variable.
For example, the code below:
$clear_conf_var()
set quote $conf_var($(cnum) daily_quote)
ensures that the user has the most up-to-date value of the
conference variable "daily_quote".
You may also wish to use cooperative "advisory" locks on variable sets;
see the $lock() function in the object model pages.