mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-07-06 12:13:16 +00:00
147 lines
5.1 KiB
Plaintext
147 lines
5.1 KiB
Plaintext
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]]
|
|
```
|