No activity today, make something!
tweb-filters Extending Filters

20161127105633 cdent  

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.

FILTER_PARSERS in tiddlyweb.filters
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.
ATTRIBUTE_SORT_KEY in tiddlyweb.filters.sort
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.