<<.preamble """This explains the basics of writing a [[filter|Filters]] to select a set of tiddlers. For a more technical presentation, see [[Filter Syntax]].""">>
<$macrocall $name=".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 <<.advancedsearch-tab Filter>> tab of [[Advanced Search|$:/AdvancedSearch]]."""/>
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:
We can reverse the meaning by adding an exclamation mark `!` just before the operator. For example, we can select any tiddlers that do <<.em not>> have the <<.tag Recipe>> tag:
A sequence of separate runs will select the tiddlers that match <<.em any>> of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:
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:
This selects recipes for 3, 4 or 5 people, then filters <<.em 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 <<.em remove>> a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:
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:
<<.def "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 <<.tid Preference>> whose content is the single word <<.value Vegetarian>>, we can say
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.
<<.def "Angle brackets">> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <<.vlink currentTiddler>> variable in a filter that selects any tiddlers whose text contains the title of the current one: