How to Filter Data Elements

When you use data elements in your tree structures, all existing data elements are displayed. However, you can also display specific elements selectively by filtering them.

To apply a filter on data elements, you should use a Filters element that contains a specific filter. You can use the following filters:

• Parent ID filter
• Field filter
• Function filter

Please note that you can only apply filters to data elements (DataElements). Please also note that you can only use one Filters element within a DataElements element.

How to Filter Data Elements by Parent ID

The Parent ID filter allows you to select elements that share the same parent entity.

For example, if you keep comments to pages in one data type, it makes sense to only display comments relevant to a specific page. In these relations, a page serves as a specific parent entity to a number of comments and they can thus be selected by the ID of their parent (page).

To filter data elements by their parent’s ID, you should use a ParentIdFilter element:

1. Locate a DataElements element you want to apply the filter to.
2. Add a Filters element within the DataElements element.
3. Add a ParentIdFilter element within the Filters element.
4. Set its required attributes:

• ParentType: The type of the parent element (data type) to filter on
• ReferenceFieldName: The name of the field that is the reference to the parent type

  <Filters>
    <ParentIdFilter ParentType="Composite.Data.Types.IPage" ReferenceFieldName="PageId" />
  </Filters>

^{Listing 19: Filtering data elements by parent ID}

Please note that a Filters element can only contain one ParentIdFilter element.

How to Filter Data Elements by Field

The Field filter allows you to select data elements if a field given contains a value that matches a specific value or a range of values.

To filter data elements by field, you should use a FieldFilter element:

1. Locate a DataElements element you want to apply the filter to.
2. Add a Filters element within the DataElements element.
3. Add a FieldFilter element within the Filters element.
4. Set its required attributes:

• FieldName: The name of the field to filter on
• FieldValue: The value of the field for which the elements will be shown

If necessary, set its optional attribute:

• Operator: The relation between the field and the value to select elements when filtered if they match

<Filters>
  <FieldFilter FieldName="Done" FieldValue="False"/>
</Filters>

^{Listing 20: Filtering data elements by field}

Please note that a Filters element can contain as many FieldFilter elements as you need.

How to Filter Data Elements with CMS Functions

The Function filter allows you to use a CMS function to filter data elements. In this case, it is the function that sets the filtering rules and is quite transparent to the Function filter that uses it.

To filter data elements with a CMS function, you should use a FunctionFilter element:

1. Locate a DataElements element you want to apply the filter to.
2. Add a Filters element within the DataElements element.
3. Add a FunctionFilter element within the Filters element.
4. Add a f:function element within the FunctionFilter element.
5. Set its required attributes:
   • name: The name of the CMS function

   If the function requires so:

6. Add one or more f:param elements within the f:function element.
7. Set its required attribute:

• name: The name of the CMS function’s parameter

If necessary, set its optional attribute:

• value: The value of the CMS function’s parameter

<Filters>
  <FunctionFilter>
    <f:function name="UpcomingEventsFilter"
      xmlns:f="http://www.composite.net/ns/function/1.0">
      <f:param name="IncludeToday" value="true" />
    </f:function>
  </FunctionFilter>
</Filters>

^{Listing 21: Filtering data elements with a CMS function}

(The CMS function schema is defined in a separate schema definition file located at:

~/Composite/schemas/Functions/Functions.xsd)

The Filters element can contain as many FunctionFilter elements as you need.

Please note that a CMS function can contain another CMS function.

Please also note that the filter function’s parameters can be assigned dynamic field values (see the example below).

Example of Creating and Using a Filter Function

Let’s assume that we have two datatypes: Demo.ParentType and Demo.ChildType. Both datatypes have the “Title” field of the String type. Besides, Demo.ChildType has the String field named “ParentIdList” which uses the DataIdMultiSelector widget referring to Demo.ParentType as its source datatype.

By using the DataIdMultiSelector, Demo.ChildType can have multiple parents.

When we build a tree of parent data elements of the Demo.ParentType type which nest elements of the Demo.ChildType type, we need to filter the child elements by their multiple parent items.

ParentIdFilter can only filter by one parent ID. And this is where FunctionFilter come in handy.

First we create a C# function that can filter Demo.ChildType by multiple parent IDs:

public static Expression<Func<Demo.ChildType, bool>> IdListFilter(Guid ParentId)
{
  Expression<Func<Demo.ChildType, bool>> filter = f => f.ParentIdList.Contains(ParentId.ToString());
  return filter;
}

^{Listing 22: An example of a filter function}

Then we use the function in our tree definition passing to its ParentId parameter a dynamic field value:

<DataElements Type="Demo.ParentType" Label="${C1:Data:Demo.ParentType:Title}">
  <Children>
    <DataElements Type="Demo.ChildType" Label="${C1:Data:Demo.ChildType:Title}">
      <Filters>
        <FunctionFilter>
          <f:function name="Demo.IdListFilter" xmlns:f="http://www.composite.net/ns/function/1.0">
            <f:param name="ParentId" value="${C1:Data:Demo.ParentType:Id}"/>
          </f:function>
        </FunctionFilter>
      </Filters>
    </DataElements>
  </Children>
</DataElements>

^{Listing 23: An example of using a filter function}