{filter:ids:expression:equals:operator}

Description

Filters a list of item ids by evaluating an expression for each item and comparing the result to a value. It returns the ids that pass, joined by dashes and kept in the same order as the input list. The expression is evaluated against each listed item, so refer to that item with its _#ALIAS aliases (a field-getter would read the rendering item instead). The operator chooses how the expression value is compared to equals: omit it for an exact match, or pass != , contain, !contain, isset, notset, or intersect. isset and notset ignore the equals value and test only whether the expression value is empty. Filtering in the database with ids is usually faster, but filter is handy when you already hold a set of ids and want to narrow it. Internally filter is a thin wrapper over aggregate with one of its filter functions.

Parameters

ids required default (empty)

Dash-separated list of item ids to filter (long or short ids). The order of the surviving ids in the result follows the order of this list.

expression required default (empty)

An AA expression evaluated for each item, using that item's _#ALIAS aliases (for example expression or a field alias). Its value is what the operator compares. A field-getter like {headline........} would read the rendering item instead, so use aliases here.

equals optional default (empty)

The value the operator compares each item's expression value against. For isset and notset it is ignored (leave it empty). For intersect it is a dash-separated set.

operator optional default (exact match)

How the expression value is compared to equals. Omit it (or pass an unknown value) for an exact equality match. See Allowed values for the recognised operators.

Examples

test

{filter:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7:_#HEADLINE:Gamma}

Expected5726c2c6b035d7aab450d1794e9e90d7

Actual5726c2c6b035d7aab450d1794e9e90d7

With no operator filter keeps only the ids whose expression value exactly equals the 4th argument. Here only Gamma matches, so its id is returned. The expression uses the target item alias _#HEADLINE (a field-getter like {headline........} would read the rendering item, not the listed items).

test

{filter:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11:_#HEADLINE:Gamma:!=}

Expecteda65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11

Actuala65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11

The != operator inverts the exact match: it keeps every id whose expression value differs from the 4th argument. All four non-Gamma ids are returned in input order.

test

{filter:a65d19971986e750761f0efcd9a16b1b-5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11:_#LONGTEXT:blue:!contain}

Expecteda65d19971986e750761f0efcd9a16b1b-968af6a9749d42bffb3045e75e3f7a11

Actuala65d19971986e750761f0efcd9a16b1b-968af6a9749d42bffb3045e75e3f7a11

!contain is the opposite of contain: it keeps the ids whose expression value does NOT contain the 4th argument. Alpha and Epsilon survive; Gamma and Delta are dropped.

test

{filter:a65d19971986e750761f0efcd9a16b1b-4f3362a62847fe1f8c59ba28a92d42c0-5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11:_#SWTCHVAL:1}

Expecteda65d19971986e750761f0efcd9a16b1b-5726c2c6b035d7aab450d1794e9e90d7-968af6a9749d42bffb3045e75e3f7a11

Actuala65d19971986e750761f0efcd9a16b1b-5726c2c6b035d7aab450d1794e9e90d7-968af6a9749d42bffb3045e75e3f7a11

A switch (checkbox) field formats to 1 when on and to an empty string when off. Filtering the five items by _#SWTCHVAL equal to 1 keeps Alpha, Gamma and Epsilon, returned in the same order as the input list.

virtual{filter:a65d19971986e750761f0efcd9a16b1b-968af6a9749d42bffb3045e75e3f7a11:_#PHONE___::isset}

Expected(ids of items whose _#PHONE___ field is non-empty)

Actuala65d19971986e750761f0efcd9a16b1b-968af6a9749d42bffb3045e75e3f7a11

isset keeps ids whose expression value is non-empty after trimming, and ignores the equals argument (leave it empty). It is the way to keep only items that have filled in a given field. This example is illustrative because the stable test items have no empty text field to split on.

virtual{filter:a65d19971986e750761f0efcd9a16b1b-968af6a9749d42bffb3045e75e3f7a11:_#PHONE___::notset}

Expected(ids of items whose _#PHONE___ field is empty)

notset is the complement of isset: it keeps ids whose expression value is empty after trimming, again ignoring the equals argument. Use it to find items that are missing a value. Illustrative for the same reason as the isset example.

test

{filter:a65d19971986e750761f0efcd9a16b1b-5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11:_#HEADLINE:Gamma-Delta-Xx:intersect}

Expected5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741

Actual5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741

intersect treats both the expression value and the 4th argument as dash-separated sets and keeps an id when the two sets share at least one element. Gamma and Delta appear in the set Gamma-Delta-Xx; Alpha and Epsilon do not.

test

{filter:a65d19971986e750761f0efcd9a16b1b-5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741-968af6a9749d42bffb3045e75e3f7a11:_#LONGTEXT:blue:contain}

Expected5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741

Actual5726c2c6b035d7aab450d1794e9e90d7-aa89ddc95136b966e6ec1419a2963741

contain keeps ids whose expression value has the 4th argument as a substring. Gamma (red green blue) and Delta (keyword blue) contain blue; Alpha and Epsilon do not. The match is case-sensitive.

← All expressions