This section explains how character data in the generated HTML output are encoded. The are various aspects of this theme, and it is quite easy to get totally confused. Because of this, I will first explain how character data change their encoding type during the processing steps by default, and later, how this behaviour can be modified.

Most of the character data are read from the XML files containing the UI definition, but some strings are also dynamically added by the program (e.g. read from a database, or another background store). The XML data are parsed, and the result is an in-memory representation as XML tree. This tree can be seen as a reference point of the various recoding steps as it expresses what is meant. This becomes clearer by an example:

<ui:variable name="company">
  <ui:string-value>Meyer &amp; Son</ui:string-value>
</ui:variable>

  |
  ui:variable
      |
      +-- attribute "name" has value "company"
      +-- ui:string-value
              |
              +-- text "Meyer & Son"

Of course, there are many more data structures than just XML trees. We have declared a variable here, and this creates a container for the variable. The important point is that the initial value of the variable can be directly taken from the XML tree, here it is "Meyer & Son". If the value is later changed (e.g. overwritten by some database record), no encoding changes are necessary. The general idea is that the internal representation never escapes characters.

In order to get HTML output, the XML tree needs to be transformed, for example, template calls must be expanded. The transformation never changes the way character data are encoded.

The result of the transformation step is an HTML tree that must be written as text stream. There are essentially two major cases:

• Element context: This simply means that the HTML node to write occurs within an outer HTML node as sub element. HTML tags are printed with the normal tag syntax: <tag>...</tag>. Character data are HTML-escaped, i.e. < is printed as &lt; etc.

  For example, this HTML tree

    |
    b
    |
    +-- text "Meyer & Son"
  

  is printed as

  <b>Meyer &amp; Son</b>
  

  It is also possible that the HTML node has attributes. These are HTML-escaped, too, e.g. if the value attribute has the value "Meyer & Son", the whole input element is printed as:

  <input type="button" value="Meyer &amp; Son">
  

• Attribute context: Here, the HTML node to write occurs inside the attribute value of an outer HTML node. What? Well, this is a consequence of the template expansion algorithm. For example:

  <ui:template name="bold_meyer">
    <b>Meyer &amp; Son</b>
  </ui:template>
  ...
  <ui:template name="make_button" from-caller="value">
    <input type="button" value="$value"/>
  </ui:template>
  ...
  <t:make_button>
    <p:value><t:bold_meyer/></p:value>
  </t:make_button>
  

  Here, the HTML subtree <b>Meyer &amp; Son</b> is finally inserted as the value of the value attribute! The tree looks like:

    |
    input
    |
    +-- attribute "type" has value "button"
    +-- attribute "value":
          |
          +-- b
              |
              +-- text "Meyer & Son"
  

  This case is handled in two steps. First, the HTML subtree within the attribute is linearized into a single string. Second, the string is printed as attribute, and this is the same algorithm as above, i.e. HTML meta characters are escaped.

  Linearization: HTML elements are printed in tag notation. Text nodes are simply left as they are, i.e. no HTML-escaping happens in this step.

  In the example, the result of the linearization is the string "<b>Meyer & Son</b>", and this string is printed as attribute, leading to the final result

  <input type="button" value="&lt;b&gt;Meyer &amp; Son &lt;/b&gt;">
  

  I know that it is a bit surprising that this case exists, but I think it is treated in a straight-forward way.

One drawback of the normal output encoding is that it is impossible to generate raw HTML dynamically. Imagine you have a database containing HTML pages. How do you include the pages into your generated output?

Let us assume the variable html_page contains the page. If you include it by

<ui:dynamic variable="html_page"/>

It is possible to force the algorithm that is used for attribute context. The important point is that this algorithm does not escape within text nodes. The ui:special element selects this algorithm, e.g.

<ui:special>
  <ui:dynamic variable="html_page"/>
</ui:special>

The HTML pre tag preserves the formatting of the inner character block. Sometimes it would be nice to simulate the effect of pre without using it, by replacing spaces with &nbsp;, newlines with <br>, and by expanding tabs. The ui:encode element allows one to add an escaping algorithm to the current active set of encoders:

<ui:encode enc="pre">
This is the first line.
Second line.
</ui:encode>

This&nbsp;is&nbsp;the&nbsp;first&nbsp;line.<br>
Second&nbsp;line.<br>

Another example: You want to generate a Javascript function that pops up an alert box on the screen:

<ui:template name="alert" from-caller="body">
  <script type="text/javascript">
    <ui:special>
window.alert("${body/js}");
    </ui:special>
  </script>
</ui:template>

The following names can be used in ui:encode, and when expanding parameters (${param/encname}) and in bracket expressions ($[expr/encname]):

• html: The HTML-escaping algorithm substitutes &lt; for <, &gt; for >, &quot; for ", and &amp; for &.

• pre: This encoding substitutes &nbsp; for spaces, <br> for newline characters, and expands tabs (tab width is 8).

• para: Multiple newline characters are replaced by <p>.

• js: The characters \, ", ', <, % and control characters are escaped according to the Javascript rules such that the string can be used inside a Javascript string literal.

• jslong: A problem of js is that Javascript interpreters do not like long lines. To be on the safe side, jslong should be used instead. It puts "+\n+" sequences into the string to avoid that the resulting lines become too long.

You can define your own encodings by calling the method add_output_encoding of the application object.

The encodings can be referred to at a number of places:

• ui:encode: The element ui:encode applies the encoding to what is printed for the subelements.

• Parameters: The syntax ${param/enc} applies the encoding enc to the value of the template parameter param.

• Bracket expressions: The syntax $[expr/enc] applies the encoding enc to the result of the bracket expression expr.