TiddlyWiki Filter language
A collaborative text on Filter Language
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 concider the following;
[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 tag tagname
(which can be zero or more).[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 tagged tagname
.For the convenience of users and designers of filters, the result of a filter is automaticaly âdeduplicatedâ, meaning repeated titles are remove keeping the list a set of unique titles.
[tag[tagname]] [tag[othertag]]
which will list all tiddlers with the tagname and othertag. But what it one particular tiddler had both tags?Filters also can be concidered to return true or false,
+[limit[1]]
at the end to ensure its only true once, that is we limit the results, if any, to 1.<$list filter="[tag[tagname]] +[limit[1]]" variable=~>
Content used, if there is even one tiddler in the wiki with the tag "tagname".
</$list>
<<~>>
<<currentTiddler>>
.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.
[title[one]] [title[tiddler two]] [title[tiddler-c]]
[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.
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}
.[<variablename>match{!!myfield}]
note the outer [
]
are used to make this a Filter Run.
<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
list[]
, enlist[]
, enlist-input[]
, subfilter[]
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.
filter={{!!filterfield}}
.
filter=<<variable>>
.{{{ yourfilter }}}
where we have no need for any widget.
{{{ [tag[tagname]] }}}
will produce a list of tiddlers with the tagname, directly where it is written.name={{{ [tag[tagname]first[]] }}}
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 ]] }}}
{{{ [[string or title]addsuffix[ concatinated]] }}}
{{{ [<variable>] [{!!fieldname}] [<macroname param>]] }}}
produces a list and will Not concatinate the values.
{{{ [<variable>] [{!!fieldname}] [<macroname param>]] +[join[ ]] }}}
Note we are joining them with a single space.
Note: It is importiant to remember what was covered in the section No repeated titles when manipulating strings. There are plenty of workarounds.
Excellent writeup!
I hope other join us and help to this wiki thread, later we can publish this as a separate TW on tiddlyhost (e.g. filter-language.tiddlyhost.com)
I am thinking to add some other parts as below
[, {, <,...
)In relation to case studies it seems to me there is possibly a dozen common filters, up to 50 regular filters and not more than 50 more to cover most cases.
In particular we need to expand examples to filters that use real world variables, fields and macros. Too many on tiddlywiki were documented in a rush to explain an operator and are somewhat artificial.
I see value in developing a package of standard real world data both in plugins and json files, against which such examples can act on. The result is people become familular with the data which helps with understanding the examples. If the data can be understood through general knowledge all the better.
Data Set ideas;
The official documentation have a good point (for me), it is concise. But it doesnât give any hint to guide you, the following tiddler to read is not clear.
For description we can do a modification of https://tiddlywiki.com/#Filters , somethin like (with better English)
You can think of TiddlyWiki as a database in which the records are tiddlers. A database typically provides a way of discovering which records match a given pattern, and in TiddlyWiki this is done with filters.
A filter is a concise notation used for return a particular result, known as its output, from the content of the TiddlyWiki (where it is used). This output can be a selection of data stored in your TiddlyWiki. You can also obtain a (list of) new value(s) generated from the original data.
The filter can be used inside of the different mechanisms of TiddlyWiki, which are used to add content in a tiddler. These are transclusion, macros and widgets.
A filter output can change as tiddlers are added and deleted in the wiki. TiddlyWiki recalculates on the fly, automatically updating any filter-based counts or lists as well.