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

Introduction to filter notation

 3rd November 2020 at 11:14am

This explains the basics of writing a filter to select a set of tiddlers. For a more technical presentation, see Filter Syntax.

Tip
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. It means that TiddlyWiki will filter for the exact string found between the brackets. But two other kinds of bracket are possible:

Curly brackets {} mean that the parameter is a TextReference, and it will be replaced with content from another tiddler. For example, if we have a tiddler with the title Preference whose content is the single word Vegetarian, we can say

[tag{Preference}]

In this simplest form the TextReference will take the full content of the tiddler (in technical terms, the text field of the tiddler) and substitute it in place of the TextReference. This way the tiddler's content will become the filter parameter, just like if you have written [tag[Vegetarian]]. But it gives you the added flexibility to change the parameter by changing the content of the Preference tiddler.

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>]

Note that these special brackets cannot be nested. It is not possible for example to write [search{<currentTiddler>}].

Multiple parameters

Introduced in v5.1.23 Some steps accept multiple parameters which are separated by a , character.

Example: [param1],[param2] or <param1>,{param2}