6th
Simplewiki for TiddlyWeb
I’ve created a plugin for TiddlyWeb that provides a very simple wiki that adheres to some old school wiki ways, including links to other pages being CamelCase, the editor being a simple textarea, and RecentChanges being provided with the same link-space as the “normal” pages. It uses markdown as its syntax, with the addition of WikiLinks.
You can get it as tiddlywebplugins.simplewiki from PyPI. The PyPI page includes installation information. The code is on github.
You can see a running version at http://simplewiki.peermore.com/wiki Feel free to play around there.
I made it as a demonstration showing how to create a particular type of application with TiddlyWeb and tiddlyweb plugins. We’ve identified a few different application types in the TiddlyWeb universe:
- Those that exercise its identity as a server-side for TiddlyWiki.
- Those that exercise its identity as a headless RESTful document store.
- Those that use it as building blocks for web apps.
Simplewiki is the latter. It is a rather small amount of code that assembles other TiddlyWeb plugins as Python dependencies and packages them with an install script and the small amount of data required to get things rolling.
Note that though there have been calls for a canonical TiddlyWeb application, I don’t think this can be called one, because it only covers one aspect of TiddlyWeb application creation, and the easy aspect at that. However it is probably a useful base case for all types.
It’s probably most informative to go look at the code but the following provides an overview of how things are put together.
tiddlywebplugins.simplewiki, the Python package, started life as a copy of the pluginmaker, which provides basic fill in the blank templates for starting a TiddlyWeb plugin project. Once those blank are filled in, it is a matter of adding functionality and the pieces to support that functionality.
All of the output from SimpleWiki is HTML, so it uses the do_html decorator from tiddlywebplugins.utils to wrap web handlers with code that ensures HTML output. That output is generated from templates which are managed by the tiddlywebplugins.templates package. Fed into those templates is text that has been rendered to html by the tiddlywebplugins.markdown package.
The text comes from tiddlers stored in a configurable recipe which can optionally use bags that have policies constraining access to read, write and create the tiddlers. Tiddlers, recipes, bags, policies and authentication and authorization handling all come from core TiddlyWeb. The wiki URL route is mounted via a handler in the simplewiki plugin which adds to the routes table managed and presented by core TiddlyWeb.
To make it easy to create a new wiki, Simplewiki includes a script called simplewiki that gathers up data from the plugin and provides it to tiddlywebplugins.instancer. Instancer is described as “A TiddlyWeb plugin to simplify instance management for verticals.” This is exactly what it does. The simplewiki script runs, creating a new instance including a store with a default configuration and a recipe name “wiki” that refers to a bag named “wiki” that contains a tiddler named “FrontPage”. The bag and recipe information are contained in a python module (tiddlywebplugins.simplewiki.instance), and the tiddler is included as package data (i.e. a file contained in the package accessible by Python code). This instancer functionality is extremely powerful and will only get more so as it is improved with use.
If simplewiki is not used, the tiddlywebplugins.simplewiki may be added to any existing instance in the usual way: By adding it to ‘system_plugins’ in tiddlywebconfig.py. If that’s done then a recipe will need to be configured for the wiki to use as its data source.
So with just the basic package you get a simple functional wiki that can be configured to use access control if you like. Stop reading now if you don’t need more more than that.
But wait, there’s more!
Because the tiddlywebplugins.templates package is being used to manage templates, if a directory called templates is present in the instance, it will be checked first for templates before checking the package data. This means you can override the templates with your own, per instance.
You can add Atom feed support by installing the tiddlywebplugins.atom, and providing a link (via the templates) to the Atom feed of the recipe driving the wiki.
You can use recipe_templates to provide context dependent tiddlers in the recipe used to drive the wiki.
Simplewiki is a plugin, but is also pluggable itself. You can add PageName, function pairs to the SPECIAL_PAGES dictionary to add dynamic pages to the wiki (this is how RecentChanges works).
Creating this plugin has been a good experience as it has helped point out both strengths and weaknesses in the TiddlyWeb core, other plugins and the instancer system. Those other pieces will improve as a result. Simplewiki’s own code is quite verbose, but with some refactoring, it could probably become very small. There’s a lot of what people like to call boilerplate (that I call transparency) that could be hoisted to utility modules. If this happens then plugins will become still more focussed on just being and showing what they do, not how they do it.
