Dynamic Configuration (Filter)

In some cases it may be useful to design a site configuration dynamically, e.g. to distinguish between a development and a production setup. For that you can use the built-in configuration Filters and Dynamic Attribute Values described below.

The context node of the expressions in both mechanisms is the root element of the Delivery Context document (fit://request/dc). Every expression described below must be a valid XPath expression. The result of the filtering should always stay a well-formed XML document.

The Filters and Dynamic Attribute Values are always automatically enabled only for the following FIT configuration files:

Filters

There are three ways of DOM content filtering:

simple filtering of a single DOM element (if attribute)
simple filtering of several DOM nodes (if element)
filtering of several DOM nodes with alternatives (choose element)

Simple filtering of a single DOM element

An if attribute marks its owner element to be filtered conditionally. Its value is the condition for retaining the element in the document. This is equivalent to wrapping the element into an if element (see below).

if attributes are not allowed in the aforementioned control structure elements like if, choose, when and otherwise.

Example

<flow>
  <redirect location="http://example.com" rewrite="false" if="client/bot" />

  <default-request />
  <parse />
</flow>

Simple filtering of several DOM nodes

An if element wraps content to be filtered conditionally. The required test attribute indicates the condition for retaining the wrapped content in the document.

Example

<sources>
  <source>
    <if test="client/hw/type = 'desktop'">
      <header name="X-HW-Type" value="Desktop" />
    </if>
  </source>
</sources>

Filtering of several DOM nodes with alternatives

The choose element wraps several content alternatives to be filtered conditionally. Alternatives are wrapped in the when or otherwise elements. The content of the first when element with a matching XPath expression given in the required test attribute is retained. If there is no matching when element, the content within the otherwise element is retained. A choose element must contain at least one when element.

Example

Dynamic URL mapping depending on the server role (development, test or live system).

<urlmap mandatory="true">
  <choose>
    <when test="server/role = 'devel'">
      <map path="/" source="//development.example.com/" />
    </when>
    <when test="server/role = 'test'">
      <map path="/" source="//test.example.com/" />
    </when>
    <otherwise>
      <map path="/" source="//production.example.com/" />
    </otherwise>
  </choose>
</urlmap>

Dynamic Attribute Values

To increase the usefulness of the Filters it is possible to dynamically evaluate attribute values at runtime.

Syntax

Dynamic Attribute Values consist of a valid XPath expression surrounded by curly braces ({ and }).

At run time, the curly braces around the expression will be stripped and the remaining attribute value will be evaluated used as the XPath expression. Therefore, multiple pairs of braces like in x="{y}_{z}" will result in an XPath error at runtime.

A workaround may look like: x="{concat(y, '_', z)}"

Example 1

<sources>
  <source>
    <header name="X-FIT-Client-Dim" value="{concat(viewport/width, 'x', viewport/height)}" />
    <header name="DPR" value="{viewport/device-pixel-ratio}" />

    <!-- Sends X-Foo=Bar if the XPath defined in rules.xml (see below) evaluates to true. -->
    <header name="X-Foo" value="Bar" if="{fit-document('fit://site/conf/rules.xml')/rules/is-production}" />
  </source>
</sources>

An appropriate rules document fit://site/conf/rules.xml may look like this:

<rules>
  <is-production>server/role = 'prod'</is-production>
  <is-debugging-enabled>request/debug = true()</is-debugging-enabled>
</rules>

Example 2

Another dynamic URL Map using Dynamic Attribute Values.

<urlmap mandatory="true">
    <map path="/" source="{concat('//', server/role, '.example.com/')}" />
</urlmap>

Errors

If the braces contain an invalid XPath expression, the attribute’s value will be replaced with an empty string ("").

Debugging

Every evaluation of a Filter or Dynamic Attribute Value provides information in the debug output.