What is filtering used for?

You may want to show or hide blocks of widgets in your backend template, because you are only concerned with a subset of elements displayed on your screen at a given moment. An example is a document containing multiple languages. You only want to edit the fields belonging to one language, one language at a time.

How to

To show/hide elements in your backend template, while you're editing, you need to specify two things:

• a widget in your layout definition, which will determine the state of your template (i.e., which parts are shown). This is typically an outputfield, but can also be a regular widget (defined in your schema).
• a businesslogic rule per block of content (template) which can be toggled on or off.

The outputfield widget

First, let's look at the widget which will determine the state of your document. In your layout, specify an outputfield (somewhere inside a template element), like follows:

<outputfield id="languageOutput" type="dropdown">
  <submit-on-change/>
</outputfield>

An outputfield is purely used for presentational purposes; its value is not stored in your final XML. The type attribute is required and currently can only be set to "dropdown". The submit-on-change tag tells the editor to reload the page whenever the outputfield's value changes. This is necessary to show/hide elements based on the outputfield's value.

Filling the outputfield's dropdown list

To add items to the outputfield's dropdown, add a businesslogic rule for the outputfield. An example:

<selectionsource choose-item="false" src="repository://content/lists/languages.xml" type="nodetree" dynamic="true"/>

See Layout reference for an explanation of the selectionsource element.

The filter element in your business logic

The filter element can be used to show / hide everything inside a template (in your layout definition). This is done by comparing a case value with a match value. If the two values match, everything inside the template is shown.
An example for the /document/meta element:

<rule for="/document/meta">
  <filter>
    <case><widget-value id="showFullContents"/></case>
    <match><value>true</value></match>
  </filter>
</rule>

In this example, all elements defined in the template for /document/meta will be turned off when the widget "showFullContents" == true. You must have a layout template for the element which you want to show/hide:

<template name="/document/meta">
  <!-- filtered content -->
</template>

In both the case and the match element, you can use these two child elements:

• widget-value : refers to a value of a widget. The id attribute refers to an output widget, or a widget defined in the schema. An example:
  code
  <widget-value id="/document/content/@lang"/>
  code

• value : a constant value. Its text content is the value which is used, eg:
  code
  <value>A constant value</value>
  code

Filtering repeated elements

To filter repeated elements, you'd typically want to use an attribute on the repeated element, which will be matched against a "case" element:

<rule for="/document/pages/page">
  <filter>
    <case><widget-value id="languageOutput"/></case>
    <match><widget-value id="@lang"/></match>
  </filter>
</rule>

The result is: every page inside the pages element will be shown only when the page 's attribute @lang matches the value of the languageOutput widget (an outputfield element in your layout). Note that the match widget's id is a relative xpath, relative from the pages element. This is allowed and necessary for repeated elements . The only restriction is that the path to a case/match widget is unique, i.e. there is only one XML element with such an xpath.