TiddlyWiki Filter language
A collaborative text on Filter Language
[Updated] Some “prose” that may help new and developing users.
TiddlyWiki filters are a key feature in tiddlywiki that grant substantial power to users and designers. Becomming proficent in writting filters is very rewarding. To help come to terms with how they work consider the following;
filters
- Filters are a long established metaphore which refers to selectivly allowing some members of a larger list or set through, to form a new list, according to a set of conditions “The filter”. It can also be thought of as removing some members of a larger list or set.
- To demonstrate this, there is an implied all tiddlers at the begining of filters which includes all tiddlers, then the filter you write applies a selective process to this list. All referes to regular tiddlers (that are not system tiddlers, or not shadow tiddlers)
Lists and titles
- Filters are primarily used to filter lists of tiddler titles, but can be used to filter any list or the simpler cases of zero, one or more.
- So a basic filter is to filter out from the list of all tiddlers with a specific tag
[tag[tagname]]here we assume the input is a list of all tiddlers and the filter says “if it has the tag tagname”. The result will be all tiddlers with the tagtagname(which can be zero or more). - A common list of one item is the current tiddler,
[all[current]]which replaces the implied[all[tiddlers]]such that, if the currentTiddler value is available, all that is returned is the currentTiddlers title. So if we combine this with the last filter[all[current]tag[tagname]]the currentTiddlers title will only “pass through the filter” if the current tiddler is taggedtagname.
- So a basic filter is to filter out from the list of all tiddlers with a specific tag
- Since lists are commonly tiddler titles, it is important top be aware of the default of No repeated titles, please see Dominant Append.
No repeated titles
For the convenience of users and designers of filters, the result of a filter is automatically “deduplicated”, meaning repeated titles are remove keeping the list a set of unique titles.
- For example consider this filter
[tag[tagname]] [tag[othertag]]which will list all tiddlers with the tagname and othertag. But what it one particular tiddler had both tags? - We would not want that particular tiddler to be listed twice, and it will not be. TiddlyWiki calls this Dominant Append
- If you need to alter this behaviour, such as when doing maths or string manipulation see Dominant Appendhttps://tiddlywiki.com/#Dominant%20Append and Filter Expression for use of the “=” prefix, “:All” run prefix and Mathematics Operators
True and False
Filters also can be considered to return true or false,
- if nothing is returned, the filters the result can be considered false,
- if anything at all is returned, the filters result can be considered true
- Although it may be true more than once (returning multiple titles), there are methods such as adding
+[limit[1]]at the end to ensure its only true once, that is we limit the results, if any, to 1.
- Although it may be true more than once (returning multiple titles), there are methods such as adding
- Often when we are testing for a condition such as true OR false we do not actually need the resulting value, and we certainly don’t want the currentTiddler variable changed. So we tend to set the result to an arbitrary variable name.
<$list filter="[tag[tagname]] +[limit[1]]" variable=~>
Content used, if there is even one tiddler in the wiki with the tag "tagname".
</$list>
- In the above example, since we do not care which tiddler is the first with this tag, we set the variable name to “~”
<<~>>- so it does not set the variable “currentTiddler”
<<currentTiddler>>.
- so it does not set the variable “currentTiddler”
Titles and strings
A very simple filter is one or more titles such as one [[tiddler two]] tiddler-c.
The [[ ]] is used because there is a space in the tiddlers name.
- This results in a list of three titles one,tiddler two and tiddler-c.
- This way of naming titles in a filter is in effect a shorthand for
[title[one]] [title[tiddler two]] [title[tiddler-c]] - If you lookup the title Operator you will see this form
[title[one]]is a “constructor” this means the implied[all[]]is no longer applied and the result is only a list of three titles.
Note: The above very simple filter shows how a filter can be created with one or more arbitary titles wether or not an actual tiddler exists for each title.
- This demonstrates how we can introduce ‘any values’ to a filter to which we can then apply various filters, thus allowing maths or formating to be applied to any input.
Beyond literals and strings
Using <variables>,{!!fields} and <<macros>> in filters
When using filters we quickly discover we want to write filters that respond to the values in variables, fields and other tiddlers, even macros. To support the writting of such tiddlers we can use the following in filters;
-
<variablename>,<macroname macroparam>,{!!fieldname},{tiddlername},{tiddlername!!fieldname}. - For example
[<variablename>match{!!myfield}]note the outer[]are used to make this a Filter Run.- since each of these are already “delimited” by their own "braces such as
<name>{name}it is unnessasary to use[or]such as[<name>]or[{name}]in filters, unless you want this to be used as a Filter Run
- since each of these are already “delimited” by their own "braces such as
- If using variables, fields and other tiddlers in filters, there is a posibility they will return more than one title, string or value. As a result you may need to use one of the following operators to help deal with the vaues therein
list[],enlist[],enlist-input[],subfilter[]
+ Other ways to use or set a filter
We typicaly think of filters as a parameter to a widget such as the $list widget filter="yourfilter" however there are otherways to use a filter.
- If the whole filter is available in a fieldname, you can set the filter directly
filter={{!!filterfield}}.- Or similarly a variable
filter=<<variable>>.
- Or similarly a variable
- But perhaps the most valuable is the Filtered Transclusion where we use the “tripple curly braces”
{{{ yourfilter }}}where we have no need for any widget.- For example
{{{ [tag[tagname]] }}}will produce a list of tiddlers with the tagname, directly where it is written. - Or can also be used as an attribute value
name={{{ [tag[tagname]first[]] }}} - Most filters are valid as parameters and filtered transclusions, and thus filtered transclusions provide a simple way to document alternative filters.
- For example
Strings and combinations thereof
Because filters can manipulate abitary strings of characters, in addition to tiddler titles, we can use filters to format, combine (concatinate) any set of characters/strings.
Common examples include;
-
{{{ [[string or title]addprefix[This is a ]] }}}- results in This is a string or title
-
{{{ [[string or title]addsuffix[ concatinated]] }}}- results in string or title concatinated
-
{{{ [<variable>] [{!!fieldname}] [<macroname param>]] }}}produces a list and will Not concatinate the values.- However we can join them as follows;
-
{{{ [<variable>] [{!!fieldname}] [<macroname param>]] +[join[ ]] }}}Note we are joining them with a single space.- resulting in ‘value 1 value 2 value 3’
- We can also remove a prefix or a suffix and various other string operations see String Operators in Filter Operators
Note: It is importiant to remember what was covered in the section No repeated titles when manipulating strings. There are plenty of workarounds.
[Edited] I continue to develop this off line but invite people to nominate a subject area about filters, you may want such documentation to address.