Flow action set-dc

The set-dc action manipulates Delivery Context Properties for the current request.

You should think twice before changing system properties in the DC — because virtually all components of FIT rely on them. That said, there may be situations where this is the right solution for your problem.

Syntax

The set-dc action has the following attributes:

  • property="..." defining the path to the property as described in the Delivery Context, in context of /dc (required)
  • xpath="..." XPath defining the value the property will be set to. It is evaluated in the context of /dc as described in the DC document (default: true())
  • value="..." sets the property to a static value

xpath and value are mutually exclusive. If neither xpath nor value attributes are defined, the property is set to true (i.e. it will be created).

Examples:

<!-- sets JavaScript to false (why would you?) -->
<set-dc property="js" xpath="false()"/>

<!-- sets custom/myproperty to viewport width px if client is of type tablet -->
<set-dc property="custom/myproperty" xpath="concat(viewport/width, 'px')" if="client/hw/type = 'tablet'"/>

<set-dc property="custom/myproperty" />
<set-dc property="custom/myproperty" value="3"/>

Boolean values

In the DC document structure boolean values are expressed by the presence or absence of a DOM element. This makes XPath expressions very simple and readable. E.g. to determine whether a client supports JavaScript, you can use <if test="js">.

Obviously, setting boolean values with the set-action requires you to define a boolean value. This is only possible with the xpath attribute:

<set-dc property="js" xpath="true()"/>
<set-dc property="js" xpath="false()"/>

true() and false() are valid XPath expression that return boolean values. Of course you can use fancier arithmetic like request/debug and not(server/role = 'production').

It is not possible to set a boolean value with the value attribute because value will always set a text value . The following code will not remove the js element, but set its text value to the string false:

<set-dc property="js" value="false"/>

The expression <if test="js"> would still be true.

Custom properties

We distinguish between overriding system properties and adding your own custom properties. From the system perspective, adding custom properties is safe, because no built-in behaviour depends on it.

In your project you can use them to gather decisions or settings centrally. These may be your breakpoint definitions, your theme colors and so on.

While it is not enforced, we recommend putting your custom properties into the /dc/custom branch:

<set-dc property="custom/colors/main" value="green"/>
<set-dc property="custom/colors/sub" value="blue"/>
<set-dc property="custom/api-call" xpath="request/ajax and fit-document('fit://request/request')/*/query[@name = 'ver' and @value='2']"/>

We also recommend running set-dc actions as early as possible in your flow. This makes the use of your properties consistent throughout the request. In the example above, you may use custom/colors/main as a replacement in your CSS and custom/api-call in an XSLT to change the output format. Your fellow developers will recognize the custom/ convention as a non-standard information local to your project or organization.

Alternative values

You are not limited to set your properties to a value determined by an XPath. You can make use of the flow control structures to prepare alternative values by choosing between multiple set-dc actions:

<!-- sets custom/tablesize depending on viewport width -->
<choose>
  <when test="viewport/width &gt; 1200">
    <set-dc property="custom/tablesize" value="huge" />
  </when>
  <when test="viewport/width &gt; 700">
    <set-dc property="custom/tablesize" value="medium" />
  </when>
  <otherwise>
    <set-dc property="custom/tablesize" value="small" />
  </otherwise>
</choose>