This page is part of a static HTML representation of the TiddlyWiki at http://tiddlywiki.com/

Introduction to filter notation

28th February 2015 at 10:45am
Filters Learning
This explains the basics of writing a filter to select a set of tiddlers. For a more technical presentation, see Filter Syntax.

Filters do nothing if you just type them into a tiddler on their own. They need a context. An easy way to experiment with filters is to type them into the Filter tab of Advanced Search.

The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space between each one and the next:

`[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]`

You can omit the square brackets when a title doesn't contain any spaces:

`[[Recipe book]] ScrambledEggs [[Mom's apple pie]]`

The double square brackets are actually a shorthand for this:

`[title[ScrambledEggs]]`

... which gives us the general model for any filter:

`[operator[parameter]]`

For instance, here's how to select all the tiddlers that have been tagged `Recipe`:

`[tag[Recipe]]`

We can reverse the meaning by adding an exclamation mark `!` just before the operator. For example, we can select any tiddlers that do not have the `Recipe` tag:

`[!tag[Recipe]]`

Tiddlers can be filtered by other fields than just title and tags:

`[field:serving[4]]`

That example will select any tiddlers that have `4` in their `serving` field.

As the word "serving" isn't a standard filter operator (and isn't likely to become one), you can safely omit the `field:` prefix:

`[serving[4]]`

Combinations

The filters we've looked at so far have involved just one step each. But you can run several steps together like this:

`[tag[Vegetarian]!tag[soup]serving[4]]`

Notice how the entire run is contained in a single pair of square brackets.

A tiddler has to match all of the steps in a run. So the example above retrieves vegetarian recipes (other than soups) for 4 people.

A sequence of separate runs will select the tiddlers that match any of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:

`[serving[3]] [serving[4]] [serving[5]]`

If we want to ignore vegetarian recipes that serve 4, we can say this:

`[serving[3]] [serving[4]!tag[Vegetarian]] [serving[5]]`

By default, each run considers every tiddler in the wiki. But we can use a `+` sign to force a run to consider only the tiddlers that were selected by the preceding runs:

`[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]`

This selects recipes for 3, 4 or 5 people, then filters those to keep only the vegetarian ones, and finally sorts any that are left into alphabetical order of title.

In a similar way, we can use a `-` sign to remove a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:

`[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast`

Special parameters

The parameter of each step we've seen so far has been in square brackets, meaning that TiddlyWiki treats it literally. But two other kinds of bracket are possible:

Curly brackets `{}` mean that the parameter is a TextReference, and that its value is to be looked up in a specified tiddler. For example, if we have a tiddler called `Preference` whose text happens to be the word `Vegetarian`, we can say

`[tag{Preference}]`

as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time.

Angle brackets `<>` mean that the parameter is the name of a variable whose value is to be used instead. Here we use the built-in `currentTiddler` variable in a filter that selects any tiddlers whose text contains the title of the current one:

`[search<currentTiddler>]`