Additional syntax for filters can be added using plugins. See Filter Plugins for existing examples. What follows describes how to create your own. This is only relevant if you are running your own TiddlyWeb server and are capable of a) writing code in Python b) can install that code where your server is running.
There are three ways to extend the syntax, each associated with an extendable dictionary in the TiddlyWeb server process.
- Add a type of filter. select, sort and limit are the default types. In most cases when you think you want to add a type, you probably want to add to select via
ATTRIBUTE_SELECTOR. Adding a type can be useful if you want to create pretty URIs or you want to inspect entities in a way that is different from how select loops over them.
- Add an attribute by which to select. For existing attributes you can just use the attribute's name, but in the case where a calculated virtual attribute is required (e.g. counting the number of tags on tiddlers), this is the solution.
- Modify or extract a value from an attribute in order for it to be used in a sort. For instance turning the value of a field into a float instead of a string.
In each case a plugin modifies the dictionary by importing it from the module and adding or replacing a key.
The key is the string that shows up on the left hand side of the filter. The value is a function that parses the value of of the query parameter that matches the value. For example given
select=tag:bar, "select" is looked up in the dictionary and "tag:bar" is passed to the function that is found. That function returns another function which is the filter itself. Please see
tiddlyweb.filters for more details.
The key is the string that shows up to the left of a ":" in a select filter. The value is a function that returns true or false given entity, attribute, and value. For example given (again)
select=tag:bar, "tag" is looked up in the dictionary, and "tag" and "bar" are passed to the found function, along with the entity currently being checked. The function can do what it likes to determine truth. In the example above, the code is:
return value in entity.tags
which is true only if the tag "bar" is a part of the
tags attribute (which is an iterator) on the entity.
The key is the string that to the right of the "=" in a sort filter, or the right of the ":<" or ":>" in a select filter that does a sort. The value is a function that returns the value to use when sorting by the name attribute. For example given
sort=modified, "modified" is looked up in the dictionary and the found function used to do searching. In the case of modified, the function turns the modified attribute from a partial tiddlywiki timestamp, into a full 14 digit string, zero padded.
See Filter Plugin Tutorial for how to put this all together.