POSTing to TiddlyWeb
Following on with my current theme of making TiddlyWeb easier to use, especially without Javascript, I thought I'd introduce another little plugin that I've written. To sum it up in a sentence, it adds POST support to TiddlyWeb.
What this means in practise, is that you can put an HTML form in your page (TiddlyWebPages is a good place to put it), and when somebody clicks submit, the data they entered is POSTed to TiddlyWeb, which then stores it, all with no JavaScript whatsoever. Sounds simple right? Well yes, that's kind of the point.
To use it properly, you can POST to the following urls:
Essentially, you could POST any set of values you like to the above URLs, and they'd get put in the right bag as tiddlers, but some names are reserved for specific tiddler attributes. They are as follows:
There is one exception to this though - binary files. If you include a file input box and give it a name of "file", then TiddlyWeb will use that instead, and put that file into the correct bag (or recipe), as a tiddler. You can then both navigate to and view it in the usual way.
The following would be a simple example of how to use this plugin. It assumes that the plugin has been installed already (ie - added to tiddlywebconfig.py)
Its that simple. If you want this plugin, its on GitHub at http://github.com/bengillies/TiddlyWeb-Plugins/tree/master/form/
You can test it out by leaving me a comment. :)
What this means in practise, is that you can put an HTML form in your page (TiddlyWebPages is a good place to put it), and when somebody clicks submit, the data they entered is POSTed to TiddlyWeb, which then stores it, all with no JavaScript whatsoever. Sounds simple right? Well yes, that's kind of the point.
To use it properly, you can POST to the following urls:
- /bags/<bag_name>/tiddlers/<tiddler_name>
- /recipes/<recipe_name>/tiddlers/<tiddler_name>
- /bags/<bag_name>/tiddlers
- /recipes/<recipe_name>/tiddlers
Fields and Values
Essentially, you could POST any set of values you like to the above URLs, and they'd get put in the right bag as tiddlers, but some names are reserved for specific tiddler attributes. They are as follows:
- Title - this specifies the tiddler title
- Text - this specifies the text (or content) of the tiddler
- tags - this specifies the tags that you want the tiddler to have (specify these as a TiddlyWiki style space/double square bracket delimited list)
Binary Files
There is one exception to this though - binary files. If you include a file input box and give it a name of "file", then TiddlyWeb will use that instead, and put that file into the correct bag (or recipe), as a tiddler. You can then both navigate to and view it in the usual way.
Example
The following would be a simple example of how to use this plugin. It assumes that the plugin has been installed already (ie - added to tiddlywebconfig.py)
<form method="POST" action="/bags/foo/tiddlers">
<input type="text" name="title" value="Insert title here" /><br>
<textarea rows="5" cols="40" name="text">Insert text here</textarea><br>
<input type="tags" name="tags" value="tags" /><br>
<input type="submit" value="Send to TiddlyWeb" />
</form>
--- or for binary files (like images) ---
<form method="POST" action="/bags/foo/tiddlers" enctype="multipart/form-data">
<input type="file" name="file" /><br>
<input type="submit" value="Send to TiddlyWeb" />
</form>
<input type="text" name="title" value="Insert title here" /><br>
<textarea rows="5" cols="40" name="text">Insert text here</textarea><br>
<input type="tags" name="tags" value="tags" /><br>
<input type="submit" value="Send to TiddlyWeb" />
</form>
--- or for binary files (like images) ---
<form method="POST" action="/bags/foo/tiddlers" enctype="multipart/form-data">
<input type="file" name="file" /><br>
<input type="submit" value="Send to TiddlyWeb" />
</form>
Its that simple. If you want this plugin, its on GitHub at http://github.com/bengillies/TiddlyWeb-Plugins/tree/master/form/
You can test it out by leaving me a comment. :)
Comments
Binary Tiddlers and You
I want to take this opportunity to talk about the current state of binary tiddlers within TiddlyWeb, how you can use them, and to introduce some new stuff that I've been working on.
There are currently a few ways of dealing with binary tiddlers in TiddlyWeb/TiddlyWiki. If we first take a look at TiddlyWiki, we can see that binary tiddlers can be loaded in the form of base64 encoded data: URIs (see TiddlyPictoWiki for a good example of this). Indeed, the upcoming TiddlyWiki5 fully supports all of this natively (among other things).
Of course TiddlyWeb also supports binary tiddlers (setting the tiddler.type attribute determines this), with the difficulty being how to get the data into the store in the first place. For this, natively, your only real option is is to PUT it using curl and the RESTful API (more on another native option below). This works for the most part, though I wouldn't call it particularly user friendly. There is also my form plugin (see POSTing to TiddlyWeb), which I'll go into greater detail about later on.
Finally, you can use twanager, and a small plugin for importing binary content that I wrote called tiddlywebplugins.bimport. I should note first that I wrote this a few months ago and some of the functionality has since been integrated with TiddlyWeb core (specifically, the twanager command twimport) so most of this also applies to that command. The main benefit of using bimport however, is that you can guarantee that the file you're importing will always be stored as binary (javascript files or TiddlyWiki files might be a good use case). So, to install:
and then add 'tiddlywebplugins.bimport' to you tiddlywebconfig.py file. You can then import binary files with:
where the URI can be anything (eg - a file: URI). Alternatively, the twimport command can be run as:
with anything not recognised as a valid type for TiddlyWeb to use being stored as binary content. What this means is that an image will import fine, but a Javascript file, will get tagged "systemConfig" and lose its mime type. If you don't want this to happen, you should use bimport. Otherwise, twimport is probably easier (as you don't have to install an extra plugin).
A while ago I wrote a blog entry entitled POSTing to TiddlyWeb which mentioned that you could use it to upload files to a TiddlyWeb bag or recipe. I've recently updated this to support tagging binary tiddlers, and have released it to pypi. You can install it by running:
from a command line. If you were using the old version, you should probably update as the new version supports better handling of tiddler titles, in that you can now override the title of a binary file being uploaded, and the aforementioned tagging of binary content (so that you can tag for example, an image, or a pdf).
I've also created a TiddlyWiki plugin to use with it. You can find it in my SVN repository at http://svn.tiddlywiki.org/Trunk/contributors/BenGillies/TiddlyWeb/Plugins/Binary/tiddlers/BinaryUploadPlugin.js, and can import it into your TiddlyWeb store with:
To use it, simply add:
where bag:bag_name is optional and allows you to specify a different bag to the one you're currently in, edit:tags and edit:title are also optional, and allow you to add a title or tags, and tags:default_tags allows you to set some default tags if you have the edit:tags option on.
I believe that binary tiddlers now have a fairly good story in TiddlyWeb, and am quite looking forward to seeing potential applications that surface.
There are currently a few ways of dealing with binary tiddlers in TiddlyWeb/TiddlyWiki. If we first take a look at TiddlyWiki, we can see that binary tiddlers can be loaded in the form of base64 encoded data: URIs (see TiddlyPictoWiki for a good example of this). Indeed, the upcoming TiddlyWiki5 fully supports all of this natively (among other things).
Of course TiddlyWeb also supports binary tiddlers (setting the tiddler.type attribute determines this), with the difficulty being how to get the data into the store in the first place. For this, natively, your only real option is is to PUT it using curl and the RESTful API (more on another native option below). This works for the most part, though I wouldn't call it particularly user friendly. There is also my form plugin (see POSTing to TiddlyWeb), which I'll go into greater detail about later on.
Finally, you can use twanager, and a small plugin for importing binary content that I wrote called tiddlywebplugins.bimport. I should note first that I wrote this a few months ago and some of the functionality has since been integrated with TiddlyWeb core (specifically, the twanager command twimport) so most of this also applies to that command. The main benefit of using bimport however, is that you can guarantee that the file you're importing will always be stored as binary (javascript files or TiddlyWiki files might be a good use case). So, to install:
sudo pip install -U tiddlywebplugins.bimport
and then add 'tiddlywebplugins.bimport' to you tiddlywebconfig.py file. You can then import binary files with:
twanager bimport <bag_name> <tiddler_name> <URI>
where the URI can be anything (eg - a file: URI). Alternatively, the twimport command can be run as:
twanager twimport <bag_name> <URI>
with anything not recognised as a valid type for TiddlyWeb to use being stored as binary content. What this means is that an image will import fine, but a Javascript file, will get tagged "systemConfig" and lose its mime type. If you don't want this to happen, you should use bimport. Otherwise, twimport is probably easier (as you don't have to install an extra plugin).
Uploading via the Web
A while ago I wrote a blog entry entitled POSTing to TiddlyWeb which mentioned that you could use it to upload files to a TiddlyWeb bag or recipe. I've recently updated this to support tagging binary tiddlers, and have released it to pypi. You can install it by running:
sudo pip install -U tiddlywebplugins.form
from a command line. If you were using the old version, you should probably update as the new version supports better handling of tiddler titles, in that you can now override the title of a binary file being uploaded, and the aforementioned tagging of binary content (so that you can tag for example, an image, or a pdf).
I've also created a TiddlyWiki plugin to use with it. You can find it in my SVN repository at http://svn.tiddlywiki.org/Trunk/contributors/BenGillies/TiddlyWeb/Plugins/Binary/tiddlers/BinaryUploadPlugin.js, and can import it into your TiddlyWeb store with:
twanager twimport <bag_name> http://svn.tiddlywiki.org/Trunk/contributors/BenGillies/TiddlyWeb/Plugins/Binary/tiddlers/split.recipe
To use it, simply add:
<<binaryUpload bag:bag_name edit:tags edit:title tags:default_tags>>
where bag:bag_name is optional and allows you to specify a different bag to the one you're currently in, edit:tags and edit:title are also optional, and allow you to add a title or tags, and tags:default_tags allows you to set some default tags if you have the edit:tags option on.
I believe that binary tiddlers now have a fairly good story in TiddlyWeb, and am quite looking forward to seeing potential applications that surface.