14.6.17

Adaptation Instructions - DOM Filter

In HTML documents content filtering can be performed on the HTML DOM. The filter is executed after the DOM is parsed by the parse action.

There are three ways of DOM content filtering:

Additionally, it is also possible to add content to the DOM with text generation.

To use DOM filtering, it has to be activated in conf/config.xml:

<config>
  <ress>
    <dom-filter />
  </ress>
</config>

Simple filtering of a single DOM element

The ai-if attribute marks its owner element to be filtered conditionally. It can be used on all non-required HTML elements. However the result of the filtering should be a proper HTML document. The value is the condition for retaining the element in the document. It must be a valid XPath expression.

<p ai-if="path/to/property = 'foo'">conditional content</p>

This p element is only retained if the delivery context property with the XPath path/to/property has the value ‘foo’. The result will be:

<p>conditional content</p>

Simple filtering of several DOM nodes

Contexts in which the ai-if element can be used:

  • Everywhere

Content model:

Content attributes:

  • test (required)

The ai-if element wraps content to be filtered conditionally.

The required test attribute indicates the condition for retaining the element content in the document. It must be a valid XPath expression.

<ai-if test="path/to/property = 'foo'">
    <h1>conditional ...</h1>
    <p>... content</p>
</ai-if>

The content of the ai-if element are only retained if the delivery context property with the XPath path/to/property has the value ‘foo’. The result will be:

<h1>conditional ...</h1>
<p>... content</p>

Filtering of several DOM nodes with alternatives

Contexts in which the ai-choose element can be used:

  • Everywhere

Content model:

Content attributes:

  • -

The ai-choose element wraps content alternatives to be filtered conditionally. Alternatives are wrapped in ai-when or ai-otherwise elements. The content of the first ai-when element with a matching XPath expression given in the test attribute is retained. If no ai-when is selected, the content of ai-otherwise is retained.

Contexts in which the ai-when element can be used:

Content model:

Content attributes:

  • test (required)

The required test attribute indicates the condition for retaining the element content in the document. It must be a valid XPath expression.

Contexts in which the ai-otherwise element can be used:

Content model:

Content attributes:

  • -
<ai-choose>
    <ai-when test="path/to/property1 = 'foo'">
        <h1>the first ...</h1>
        <p>... alternative</p>
    </ai-when>
    <ai-when test="path/to/property2 &gt;= 100">
        <h1>the second ...</h1>
        <p>... alternative</p>
    </ai-when>
    <ai-otherwise>
        <h1>the default ...</h1>
        <p>... alternative</p>
    </ai-otherwise>
</ai-choose>

If the first condition is met, the result will be:

<h1>the first ...</h1>
<p>... alternative</p>

Otherwise if the second condition is met, the result will be:

<h1>the second ...</h1>
<p>... alternative</p>

Otherwise the result will be:

<h1>the default ...</h1>
<p>... alternative</p>

Restrictions

ai-if and ai-choose elements must not be ancestors of <html>, <head>, and <body> elements.

For example, if you want to have different <head> elements, you should not use something like this:

<!DOCTYPE html>
<html>
  <ai-choose>
    <ai-when>
      <head>
        <script src="1.js"></script>
      </head>
    </ai-when>
    <ai-when>
      <head>
        <script src="2.js"></script>
      </head>
    </ai-when>
  </ai-choose>
  <body>
  </body>
</html>

Instead, you should use this:

<!DOCTYPE html>
<html>
  <head>
    <ai-choose>
      <ai-when>
        <script src="1.js"></script>
      </ai-when>
      <ai-when>
        <script src="2.js"></script>
      </ai-when>
    </ai-choose>
  </head>
  <body>
  </body>
</html>

Text generation

In HTML documents text can be generated via the ai-value-of element.

The ai-value-of element

Contexts in which this element can be used:

Content:

  • no content

Attributes:

  • select (required)

The ai-value-of element will be replaced by the string value of the XPath expression specified by the required select attribute. Any text content or child elements will be discarded.

<span>OS: <ai-value-of select="concat(client/os/name, ' ', client/os/version)"></ai-value-of></span>

You may also use self-closing tags:

<span>OS: <ai-value-of select="concat(client/os/name, ' ', client/os/version)"/></span>

The result of both examples for an iPhone could be:

<span>OS: iOS 8.1</span>

Note that the element content is not interpreted. If you specify child nodes nevertheless, they will be replaced with the new value, because the whole element is removed from DOM.

However, since ai-value-of is not parsed as a void element like br, the closing tag is mandatory.