Bookmark and Share Share

<filter>

This statement filters the content of a variable based on a condition and places the result in a new variable. You can also simply update the input variable with filtered results.

The filter condition is defined in an XPath expression. You can use comparisons, position, XPath functions and dynamic expressions in the condition. You can also combine multiple conditions.

For examples, see <filter> Basics, Filtering Variables with Namespaces, Filtering Comparisons Using Variables, Filtering Based on Position, Using XPath Functions or Other Comparison Operations in Filtering, Combining Filter Criteria or Using Dynamic Filtering Expressions.

Can Contain Empty
Allowed In mashup, else, elseif, for, foreach, if, macro, operation, sequence, while,

Attributes

Name Required Description
inputvariable yes

The name of the input variable to filter.
filterexpr yes

An expression that defines the filter to apply to the input variable. All matching nodes are included in the result.
outputvariable yes

The required variable to accept the output of this statement.

<filter> Examples

<filter> Basics

Identify the variable to filter in inputvariable and the variable to receive the filtered output in outputvariable. Define the filter as an XPath 2.0 expression in filterexpr. This is a relative expression within the input variable.

For example:

<variables> 
  <variable name="queryResult" type="document"/> 
  <variable name="westCoastOnly" type="document"/> 
</variables> 
... 
<filter inputvariable="$queryResult" 
  filterexpr="/customers[region='West']" 
  outputvariable="$westCoastOnly"/>

The XPath predicates define the comparison criteria for the filter. See A Brief Introduction to XPath 2.0 for basic information about XPath predicates.

Filtering Variables with Namespaces

The filter expression uses XPath predicates to compare some value in the input variable to a literal value, as shown above. The path in the filter expression to find the input variable node to compare must include any namespaces used, as shown in this example: 

<!-- select all lists that have user rating info --> 
<filter inputvariable="$result" filterexpr="//ns:list[ns:rating]" 
  outputvariable="$rate"/>

You can also use wildcards to match any namespace as shown in this example:

<!-- select all lists that have user rating info --> 
<filter inputvariable="$result" filterexpr="//*:list[*:rating]" 
  outputvariable="$rate"/>

Filtering Comparisons Using Variables

You can also filter based on any variable defined in the mashup.

You reference variables using $variable-name. For example:

<input name="selectedEmail type="string"/> 
... 
<filter inputvariable="$staff" outputvariable="$result" 
  filterexpr="/personnel/person[email = $selectedEmail]"/>

Filtering Based on Position

When results contain repeating items, you can filter based on the cardinal order or position of items. You can select one specific item by number or select a contiguous group using the XPath function position(). For example: 

<!-- select the third staff member --> 
<filter inputvariable="$staff" outputvariable="$result" 
  filterexpr="/personnel/person[3]"/> 
<!-- select the first 3 staff members --> 
<filter inputvariable="$staff" outputvariable="$result" 
  filterexpr="/personnel/person[position() = (1 to 3)]"/>

Note: XPath uses 1-based position indexing.

Using XPath Functions or Other Comparison Operations in Filtering

In addition to the = operator, you can use any valid XPath operator in the filtering expression. This include >, >=, <, <= and != (not equals). For example: 

<!-- select all lists with user ratings > 5 --> 
<filter inputvariable="$result" outputvariable="$highRated" 
  filterexpr="//*:list[*:rating &gt; 5]" />

Note: you must use XML escaping with XPath operators that use the < or > characters, as this example shows.

You can also use two XPath functions, contains(string-to-search,string-to-match) and matches(string-to-search,pattern-to-match,[flags]), to handle substring comparisons. Both of these functions look for a string anywhere in the node you specify.

The contains() function does case sensitive comparisons. The example shown below selects all record nodes from the employees variable whose fname child contains "So" exactly. This would match names such as Sophy, Sonja or OnSo, but would not match Jefferson:

<!-- find employee with first name containing "So" exactly --> 
<filter inputvariable="$employees" outputvariable="$result" 
  filterexpr="/records/record[contains(fname,"So")]" />

The matches() function can do either case-sensitive or case-insensitive searches. To make the match case-insensitive, pass i in the flags parameter. You can also use regular expressions in the second parameter to do wildcard matching or handle specific patterns.

The example shown below selects all record nodes from the employees variable whose fname child contains "so" in any case. This would match names such as Sophy, Sonja and Jefferson

<!-- find employee with first name containing "so" any case --> 
<filter inputvariable="$employees" outputvariable="$result" 
  filterexpr="/records/record[matches(fname,"so","i")]" />

In addition to these two built-in functions, you can use any other built-in XPath function in a filter expression. XPath contains a wide variety of string, number and date functions to allow you to work with data. See XPath 2.0 functions for more information.

You can also create you own XPath functions and add them to the Mashup Engine to perform specific data transformations to handle specific comparisons that are unique to your organization. See Defining Custom XPath Functions for more information.

Combining Filter Criteria

You can combine criteria in a filter expression to handle more complicated filtering. Use the keywords and or or in the expression. This example filters a variable based on any one of several criteria: 

<filter inputvariable="$employees" outputvariable="$result" 
  filterExpr="records/record[matches(fname,$query,"i") or 
    matches(address,$query,"i") or 
    matches(phone,$query,"i") or 
    matches(city,$query,"i") or 
    matches(country,$query,"i") or 
    matches(dept,$query,"i")]"/>

Using Dynamic Filtering Expressions

Filtering expressions contain both a path to a node and a predicate that defines a comparison to use as the filter. You can make the value of that comparison dynamic using variables.

You can also make the path portion of filtering expressions dynamic using input parameters and dynamic mashup expressions. Dynamic mashup expressions enclose references to variables in braces ( { } ) to ensure that they are evaluated before the XPath expression itself is evaluated.

This example invokes a service and filters the results based on a path and field identified in input parameters:

<!-- input with an XPath path --> 
<input name="selectedItem" type="string"/> 
<input name="comparisonField" type="string"/> 
<!-- invoke with dynamic filter defined by input --> 
<directinvoke endpoint="http://rss.news.yahoo.com/rss/mostviewed" method="get" 
  filterexpr="{$selectedItem}[matches({$comparisonField},'Ruby')]" 
  outputvariable="$result" />

See Dynamic Mashup Expressions for more examples and information.