TiddlyWiki5/editions/tw5.com/tiddlers/filters/Introduction to Filters.tid

created: 20140410101941871
modified: 20141009180223576
tags: Learning
title: Introduction to Filters
type: text/vnd.tiddlywiki

This is a step-by-step introduction to how [[Filters]] are used. [[Filter Syntax]] presents a more technical summary of this information.

! Using Filters

Filters are a special notation for expressing lists of tiddlers within WikiText.

Filters are used in the ListMacro, TabsMacro, ListWidget, CountWidget, and many other areas of TiddlyWiki.

For example, this is how the ListMacro would be used to display the first example below:

```
<<list-links "HelloThere Introduction [[Title with Spaces]]">>
```

The easiest way to experiment with tiddler filters is by typing them into the ''Filter'' tab of the [[advanced search panel|$:/AdvancedSearch]].

! Simple Filters

The simplest example of a filter is a list of tiddler titles (if necessary quoted with double square brackets):

```
HelloThere Introduction [[Title with Spaces]]
```

The titles must be separated by one or more spaces and/or linebreaks.

! Filter Operators

Filter operators are used to select tiddlers in particular ways. For example, this filter consists of a single step that selects all tiddlers tagged ''introduction'':

```
[tag[introduction]]
```

The word `tag` is the ''operator'' and `introduction` is the ''parameter'' (sometimes called the ''operand'').

See [[Filters]] for a complete list of the available operators.

!! Default Filter Operator

The operator defaults to `title` if omitted, so `[[HelloThere]]` is equivalent to `[title[HelloThere]]`. If there are no spaces in the title, then the double square brackets can also be omitted: `HelloThere`.

! Negating Filter Steps

A filter step can be negated by preceding the operator with an exclamation mark (`!`). This example selects all tiddlers that are not tagged ''introduction'':

```
[!tag[introduction]]
```

! Operator Suffixes

Some filter operators can take an optional suffix that provides further information. For example, the `field` operator takes a suffix indicating the field to be compared. The following filter returns all tiddlers that have ''JeremyRuston'' in the `modifier` field:

```
[field:modifier[JeremyRuston]]
```

! Field Operator Shortcut

If an operator is not recognised, then it is instead interpreted as the suffix of the `field` operator. Thus, these two filters both return all the tiddlers that contain the string ''create'' in their `caption` field:

```
[caption[create]]
[field:caption[create]]
```

! Indirect Parameters

If a filter step has curly brackets around its parameter, then it is taken to be a TextReference to the actual value. For example, this filter selects all tiddlers containing the string contained in the ''$:/temp/search'' tiddler:

```
[search{$:/temp/search}]
```

! Variable Parameters

If a filter step has angle brackets around its parameter, then it is taken to be the name of a variable containing the actual value. For example, this filter selects all tiddlers containing the title of the current tiddler:

```
[search<currentTiddler>]
```

(The built-in `currentTiddler` variable keeps track of which tiddler is the current one.)

! ORing Multiple Filter Steps

You can use multiple filter steps at once. If you write the steps separately, the overall result is the set of tiddlers that match //any// of the steps. Each step is processed separately, adding its tiddlers to the overall result.

This example selects all tiddlers that are either tagged ''introduction'' or ''demo'':

```
[tag[introduction]] [tag[demo]]
```

Here's an example that returns tiddlers tagged ''alpha'' or ''beta'' that are also tagged ''task'' but not tagged ''done'':

```
[tag[alpha]] [tag[beta]] +[tag[task]!tag[done]]
```

! ANDing Multiple Filter Steps

A sequence of steps can also be combined by bashing them together and merging the outer square brackets. This is called a "run". The result is the set of tiddlers that match //all// of the steps in the run.

For example, here we select tiddlers that are tagged ''introduction'' and also tagged ''demo'':

```
[tag[introduction]tag[demo]]
```

Here's another example that selects all tiddlers tagged ''introduction'' that are //not// tagged ''demo'':

```
[tag[introduction]!tag[demo]]
```

! Negating Runs

Ordinarily, each run //adds// to the accumulated results. Prefixing a run with `-` instead causes the list of tiddlers selected to be //removed// from the results. For example, this example returns all the tiddlers tagged ''introduction'', apart from `HelloThere` and `Title with Spaces`:

```
[tag[introduction]] -HelloThere -[[Title with Spaces]]
```

This example returns all tiddlers tagged ''introduction'' that are not also tagged ''demo'':

```
[tag[introduction]] -[tag[demo]]
```

! Working with Filter Results

Usually, each run takes the entire store of available tiddlers as its source. Prefixing a run with `+` causes the results so far accumulated to be used as the source instead.

For example, this filter selects tiddlers tagged ''introduction'' or ''demo'', and then sorts the resulting list by the `title` field:

```
[tag[introduction]] [tag[demo]] +[sort[title]]
```