LXP Variables and Objects
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.
Naming Conventions
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.
Using Variables and Objects
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.
CGI Arguments
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").
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.
Direct SQL objects
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).
Global LXP objects
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.
Copyright © 2000-2007 Command Prompt, Inc. All Rights Reserved. All trademarks property of their respective owners.