When a tag is parsed, its attributes are read in one of two ways—literally, or interpretively. Similar to
existing conventions in a variety of languages, defining a value in single-quotes (e.g.,
name='value') causes the contents of the value to be parsed literally, regardless of the
characters between quotes. Using double-quotes causes its contents to be parsed interpretively, meaning that some characters
will be treated in special ways.
Specifically, these special characters are the dollar sign ($), the at sign
(@), and the ampersand (&). These characters correspond
to variable substitution, object variable value substitution, and entity substitution, respectively.
Value substitution is the process by which a variable, cookie, object, or entity's value is
substituted for its syntactically referenced name. This occurs at the name's original location in any
arbitrary string of characters.
What may be confusing to experienced programmers at first is that LXP supports the familiar dollar sign notation to
substitute a named variable (e.g., $myvariable) with its associated value in a mixed
character string.
When using LXP, it is important to understand the contexts in which variables are substituted (and the context in
which they are not). Subsequently, it is also important to understand when to use variable substitution and when not
to.
The first rule is that variables will never be substituted outside of an LXP tag. Example 13-9 attempts incorrectly to place the value of a variable named
variable within an LXP document.
Example 13-9. Invalid variable substitution
<lxp>
Here is my variable: $variable <!-- Wrong -->
</lxp>
Instead, suppose that the URL https://localhost/test.lxp?setbar=foo is opened in a browser, and
that test.lxp contains the snippet of LXP mark-up shown in Example 13-10.
Example 13-10. Valid variable substitution
<lxp>
<setvar bar="$setbar" /> <!-- sets bar's value to setbar's value -->
<putvar name="bar" /> <!-- output the value of bar -->
<lxp>
The mark-up in Example 13-10 opens an LXP region and uses the
<setvar> tag to assign the value of the variable named
setbar to a new variable named bar. Variable substitution
is correctly used in this case, because it occurs within an LXP tag.
Since the previously mentioned URL assigned a value of foo to
setbar, this means that the new variable bar will be
assigned a value of foo.
The use of the <putvar> tag introduces the second rule to watch out for in
LXP. Some tags (such as the <putvar> tag) expect to receive a literal variable name
in order to perform their job. Remember that dollar signs and at signs are not actually part of variable names; they are
only used to substitute values in place of names.
You might be inclined to think that the syntax of the <putvar> tag in Example 13-10 should have read like this:
<putvar name="$bar" /> <!-- output the value of bar -->
This would actually result, however, in the value of the variable bar being
substituted into the value of the name attribute. Since the value of the
bar variable is foo, LXP would attempt to insert a
variable with the name of foo.
The simplest way to know whether or not to use substitution characters is to remain aware of what the purpose of the
tag is. If an attribute should be substituted with a variable's value, use the
$ symbol to substitute it. If an attribute is literally specifying a variable by name, as
with the <putvar> tag, do not substitute it.
A literal dollar sign ($) may be used within double quotes by placing two of them
immediately one after the other, sequentially (e.g., <setvar price="$$99.95" />).
Note: When using substitution, if a variable with the specified name is not found, LXP will check for a cookie with the
specified name. If one is found, its value will be substituted.
The substitution of a variable value from an object is very similar to normal variable substitution. However, instead
of using the dollar sign ($) to substitute a value, you use the at sign
(@). Syntactically, the only difference between referencing a variable value with
@ instead of $ is that dots
(.) and square brackets ([]) are allowed as part of the
object name.
A literal at sign (@) can be placed inside of an attribute's value by typing the
character twice consecutively (e.g., <setvar email="jlx@@commandprompt.com" />).
LXP automatically converts any recognized entity within an LXP tag's attribute value into its literally interpreted character symbol. As of Version 0.8, LXP's recognized entities consist of the five pre-defined XML entities:
It's useful to know about entity substitution, as sometimes both apostrophes and quotes may be needed within the
value of an LXP tag attribute, making it otherwise impossible to insert them without the use of these entities. LXP's
developers considered programmatic back-slash escape sequences as a means to solve this (as is common in other programming
languages), but LXP's ability to natively handle entities both preserves the mark-up mentality and adds a new level of
sophistication to the language.
Example 13-11 provides an example of entity substitution within the LXP
<include> tag.
Example 13-11. Using entity substitution
<lxp>
<setvar field="field_two" />
<include sql="SELECT field_one, $field FROM "CAPITALIZED_TABLE""
method="SQL">
<strong>Column One:</strong> <field name="field_one" /><br>
<strong>Column Two:</strong> <field name="field_two" /><br>
</include>
</lxp>Example 13-11 demonstrates the use of entities inside of a direct SQL query in order to
place quotes within quotes. This is frequently required to make identifiers case-sensitive within PostgreSQL, as
identifiers are otherwise folded to lowercase.
When parsed, the " is changed into its literal counter-part, making the
actual executed query as follows:
SELECT field_one, field_two FROM "CAPITALIZED_TABLE"
See the Section called Including SQL Content" for an explanation of what exactly this example's LXP markup would achieve.
LXP supports a simple search-and-replace mechanism for variable values with its
<varparser> tag. This tag takes two
attributes—find and replace. When you use the
<varparser> tag, a region is opened within which any variable value that is
substituted will be filtered through the defined search-and-replace rule.
The <varparser> is primarily useful for stripping or escaping unwanted
characters. For example, in preparation to execute a SQL statement, single-quotes (') must
be prefixed by a backslash, as a single-quote delimits string constants to PostgreSQL. Example 13-12 demonstrates the escaping of single-quotes in a variable called
txt.
Example 13-12. Using <varparser> to prepare SQL
<lxp>
<varparser find="'" replace="\'">
<include sql="SELECT * FROM table WHERE txtfield = '$txt'">
<field /><br />
</include>
</varparser>
</lxp>In Example 13-12, the <varparser find="'" replace="\'">
tag instructs LXP to replace any single-quote with a back-referenced \' sequence within any
substituted variable value.
Note that this search-and-replace occurs only for substituted variable values.
As such, the literally typed apostrophes in the sql attribute of the
<include> tag are left unchanged; only the contents of variable values being
substituted within that attribute (e.g., the txt variable's value, in
Example 13-12) are modified upon their substitution.
The closing </varparser> tag puts LXP back into normal variable substitution
mode.
Note: You can configure several simultaneous search-and-replace rules by nesting several
<varparser> tags within one another.
