Tag Parsing

Variable Substitution

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.

<lxp>
  Here is my variable: $variable <!-- Wrong -->
</lxp>

Instead, suppose that the URL http://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.

<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" />).

Object Variable Value Substitution

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" />).

Entity substitution

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:

• Ampersand (&amp;)

• Less-than symbol (&lt;)

• Greater-than symbol (&gt;)

• Apostrophe (&apos;)

• Double-quote (&quot;)

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.

<lxp>
  <setvar field="field_two" />
  <include sql="SELECT field_one, $field FROM &quot;CAPITALIZED_TABLE&quot;"
           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 &quot; 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.

Using <varparser>

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.

<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.