WikklyText A wikitext server and rendering library
DRAFT
This information is preliminary and not yet (or only partially) implemented. Do not rely on any information presented here until this notice is removed.
The TiddlyWeb API works in terms of a few basic object types: tiddlers, bags, filters, rules and recipes.
- tiddler
- An individual content item. Composed of wikitext plus metainfo (title, author, date, etc.) Stored in a server-defined way. Not directly exposed to the world, but only through the /bags and /recipes interfaces.
- bag
- A container that holds any number of tiddlers. A bag is the exclusive owner of the tiddlers it contains. So bagA and bagB can both contain a tiddler named Foo, but these will be distinct objects, just as /bagA/Foo and /bagB/Foo are unique entries in a filesystem. Bags know who is allowed to read and/or write the tiddlers they contain.
- filter
- A query string appended to the end of any URI that ends with "tiddlers". In effect, performs "SELECT * from TiddlerList where FILTER" to fetch a subset of tiddlers from a given list.
- rule
- The combination of a (bag|recipe) and a filter. A rule is a URI that defines a list of tiddlers. For example:
- /bags/BagA/tiddlers
- This rule evaluates as all tiddlers in BagA
- /bags/BagB/tiddlers?FILTER_B
- This rule evaluates as all tiddlers in BagB that satisfy FILTER_B
- /recipes/MyRecipe/tiddlers?FILTER_C
- Evaluates as all tiddlers returned by MyRecipe that satisfy FILTER_C.
- recipe
- A selection mechanism that pulls tiddlers from any number of bags to create a single list that is sent to the client. When the client subsequently writes a tiddler back via a recipe URI, the server knows which bag the tiddler should be placed in based on the recipe. A recipe evaluates a list of rules to determine the set of tiddlers to be exposed through the recipe URI.
Implementation details:- On GET, if the rules list yields multiple tiddlers with the same basename (/BagA/Foo and /BagB/Foo both have a basename of Foo), the tiddler selected by the later rule is returned.
- On PUT, if the rules list yields multiple tiddlers with the same basename, the rule is that you traverse the bags in reverse order and PUT the tiddler into the first place it could go.