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:
There are three ways of DOM content filtering:
if
attribute)if
element)choose
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
.
<flow>
<redirect location="http://example.com" rewrite="false" if="client/bot" />
<default-request />
<parse />
</flow>
An if
element wraps content to be filtered conditionally. The required test
attribute indicates the condition for retaining the wrapped content in the document.
<sources>
<source>
<if test="client/hw/type = 'desktop'">
<header name="X-HW-Type" value="Desktop" />
</if>
</source>
</sources>
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.
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>
To increase the usefulness of the Filters it is possible to dynamically evaluate attribute values at runtime.
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)}"
<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>
Another dynamic URL Map using Dynamic Attribute Values.
<urlmap mandatory="true">
<map path="/" source="{concat('//', server/role, '.example.com/')}" />
</urlmap>
If the braces contain an invalid XPath expression, the attribute’s value will be replaced with an empty string (""
).
Every evaluation of a Filter or Dynamic Attribute Value provides information in the debug output.