A variable is a modifiable value in memory that is accessed through an associated name. This name
is used to identify, and subsequently utilize in some fashion, the value that it represents. The specific use varies based on
the LXP tag employed.
LXP also implements a special type of data structure called an object. An LXP object is typically
used to identify several associated variable values through a common name. The particular value you wish to address in an LXP
object is identified either by a trailing subscript (a numeric or text value, in square brackets, such as
example[0]) or a dot-notated trailing identifier (such as
for.count).
The concept of an LXP object is similar to the programmatic concept of arrays and objects in traditional programming
languages, though LXP objects are generally much simpler in their nature. In practice, the only difference between variables
and objects is syntactic, having to do with how values are identified. Variables are identified with a plain name (e.g.,
my_value), while objects are identified by a name and a secondary identifier (e.g.,
my_value[0], my_value[1], my_value.size).
From a programmer's perspective, variables and objects are considered global, meaning that once
set, they are available anywhere in a document. Included documents will also have access to the variables which are set in
memory.
The valid characters with which you may define an LXP variable's name are:
Any letter (a–z, A–Z)
Any digit (0–9)
The underscore ( _ )
The valid characters with which you define a complete LXP object's name are:
Any letter (a–z, A–Z)
Any digit (0–9)
The underscore ( _ )
The period (.)
Square brackets ([ ] )
Note that while numbers are the most common form of subscript (since they are used implicitly by CGI arrays; see
the Section called CGI Arrays"), any legal characters may be used within square brackets following an object's name (e.g.,
pseudo_array[example]).
When parsing the attributes of an LXP tag, some special character symbols may be used to
substitute the value of a variable directly into either the attribute's name or value (see the Section called Tag Parsing" for more about this technique). These characters are: the dollar sign
($) for variables, and the at sign (@) for objects.
It must be understood that while special character symbols are sometimes used to substitute
variable values into a tag's attributes, these character symbols are not part of a variable's name and
should not be used in contexts where a literal variable or object name is expected.
Variable values can be displayed anywhere in the body of an LXP region through the
<putvar> tag. Here is the syntax for
<putvar>, where variablename is the name of the
variable whose value is to be displayed:
<putvar name="variablename" />
Variable values may also be set and reset via the <setvar> and
<setvars> tags. Here is the syntax for these tags:
<setvar variablename="variablevalue" />
<setvars variable1="value1"
variable2="value2"
[...]
/>
Like variables, the values referenced by objects can also be displayed and set by the
<putvar> and <setvar> tags.
Note: Remember that the use of either a dot (period) or square brackets in setting a name with
<setvar> implies that you are setting a variable value to an
object, rather than a plain variable. Such a value can therefore only be substituted later with the
at sign, rather than the dollar sign.
Like many web-based programming languages, LXP keeps an internal list of CGI arguments that have
been passed to it. These arguments are implicitly treated by LXP as variables.
Note: For the purpose of this chapter, the terms "argument" and "variable" will be nearly synonymous. In context, the
term "argument" applies specifically to form-passed variables, while "variable" applies to any variable set in memory
(either passed by a form, or set by the developer).
Arguments are each passed from forms with a name and a value. For each
argument passed to an LXP document (e.g., via an HTML form), a single variable is created with the passed argument used as
the variable's name.
If two arguments have the same name, the last value passed by the form is used (with the exception of array values;
see the Section called CGI Arrays").
Objects are useful when handling CGI arrays. Ordinarily, if more than one argument value is
passed to an LXP document with the same argument name, the value of the last passed argument is used, and any preceding
values are ignored. However, by passing a CGI argument with a name ending in empty square brackets (e.g.,
<select name="test[]">), an LXP object will automatically have an array of values
assigned to an object bearing the name preceding the square brackets.
In other words, any argument passed from a CGI form whose name ends in square brackets (e.g.,
test[]) will be implicitly treated by LXP as an array of values. When such an argument is
passed to LXP by a submitted form, each separate value found for it is automatically set as a separate variable value in
memory, with an incrementing numeric value between the brackets following the object's name.
For example, if an HTML form passes an argument named test[] that has three values
set to its name, three variable values will be set for a test object. These values may be
referenced as test[0], test[1], and test[2], respectively.
During a direct SQL query's execution, a special object called this is used to
reference column values in the result set. Each column selected from the result set can be referenced as
this.column_name where column_name
is the name of the column.
Additionally, an object called sql is created with meta-information about the query.
These pieces of information include the number of the current row being accessed
(sql.row), the offset of the current row being accessed
(sql.offset), the number of rows last selected by a SQL query
(sql.numrows), and the number of columns last selected by a SQL query
(sql.numcols, or sql.numfields).
Two special objects named lxp and env are
pre-defined system objects that can supply information about the LXP system and environment variables.
Any environment variable set by Apache's CGI configuration (e.g., REMOTE_ADDR) can
be accessed by referencing the name of the variable as a dot-notated identifier through the
env object. For example, the env.REMOTE_ADDR variable
value identifies the address of the remote client accessing the current document (if that feature is enabled in
Apache).
The lxp object is reserved for system purposes. As of Version 0.8, only three values
are defined. The most useful of these is the lxp.self value, which describes the URI which
Apache received for the current LXP request (e.g., /app/index.lxp).
Additionally, the lxp.version variable value contains the current version of the LXP
software being used, and the lxp.copyright variable value contains the copyright on the
software.
Users submitting data to an LXP document are not able to pass variables beginning with
lxp. via a GET or POST
request. Thus, any variable beginning with lxp. is a protected
variable, and can only be set by an LXP document through the <setvar> tag. This can
be useful in maintaining the integrity of sensitive variables, such as the results of password-based authentication.