tsapp provides a tool, tsapp
, for creating browser-based applications
for use with TiddlySpace. Such applications are
made of one or more html files along with one or more CSS and JavaScript
files for presenting and access the tiddler data that lives in TiddlySpace.
The combination can be very useful for rapid development of web applications that need a persistent but simple data store with a clean, robust API.
tsapp is a Python 2 based tool. You will need a Python installation (2.5
and above). pip
is used for installation. If you don't have pip you can
learn how to get it here.
pip install -U tsapp
Once installed the tsapp
script should be on your $PATH
.
tsapp
provides a single script that takes multiple commands. Running
tsapp help
will list the relevant commands. The following lists
available commands. Those commands which are not yet completed are marked
with TBC
.
Note that the commands are designed to allow easy creation of aliases and to otherwise be combined in a useful fashion using the shell.
tsapp init <app name>
Create an app directory named whatever you give you for <app name>
.
Inside the directory will be a stub index.html
file and an assets
directory. index.html
is used as the primary access page of your
app. JavaScript, CSS, and other files go in assets.
tsapp serve
Run a local web server that will serve up your HTML file and other assets.
Any assets which are not found locally will be looked for at the target
TiddlySpace server (see configuration below). Paths to
/bags/<somebag>/tiddlers/<sometiddler>
will first try to load
assets/<sometiddler>
locally. If that is not found, then the original
path will be looked up on the TiddlySpace server.
The proxy server will always send PUT
, POST
and DELETE
requests
to the target server.
The goal with this arrangement is to allow the local files to not have to change when pushed to the target server for eventual hosting.
If wsgi_server
is set in config the value is taken as a module
containing a function start_server
which, when passed the config
will start a server.
tsapp push <bag name> [<tiddler title>]
Push (via HTTP PUT
) all the local assets to the target server, in the
bag named by <bag name>
. If the bag does not end with _private
or
_public
, then _public
will be appended. The exception to this is if
tiddlyweb_mode
is set to True in config.
Files that have a .html
or .tid
extension on the source file will
have the extension removed on the target.
If <tiddler title>
is provided, just that one tiddler will be pushed.
tsapp push_hard <bag name> [<tiddler title>]
Push (via HTTP PUT
) all the local assets to the target server, in the
bag named by <bag name>
. If the bag does not end with _private
or
_public
, then _public
will be appended. The exception to this is if
tiddlyweb_mode
is set to True in config.
This command is distinct from push
in that the target file on the
server is deleted before the PUT
.
Files that have a .html
or .tid
extension on the source file will
have the extension removed on the target.
If <tiddler title>
is provided, just that one tiddler will be pushed.
tsapp auth <username>
Authenticate to the target_server as username and write the resulting auth token to the local directory's configuration file.
tsapp delete <bag name> <tiddler title>
A convenience method for removing a tiddler that's ended up on the server that is no longer needed and may be in the way.
tsapp looks for a .tsapp
configuration file in the current user's $HOME
and in the current directory. $HOME/.tsapp
overrides defaults and
./.tsapp
overrides $HOME/.tsapp
. There is no requirement for a configuration
file in the home directory if one is not desired. However, in order
for the push
command to work, a .tsapp
containing an auth_token
must
be found. The auth
command will create one.
Make sure that you do not commit a .tsapp file that includes the auth_token.
The fields are:
The URL (without trailing /
) of the home tiddlyspace server. Defaults to
http://tiddlyspace.com
.
The hostname or IP to which to bind the local proxy. Default is 0.0.0.0
.
The port to which to bind the local proxy. Default is 8080
.
Auth secret for accessing private resources on the target server. No default.
Set it with the auth
command or copy in the tiddlyweb_user cookie.
The auth_token property will also be set (only if it does not exist already) when the server intercepts login requests to `/challenge/
If a POST to /logout
is made and the auth_token exists, it will be removed
from the configuration in the local directory.
The name of a python module containing a start_server
method which,
when passed config
, will start a web server hosting the proxy
application. Originally this was the server provided by the wsgiref
module in the Python stdlib, but this proved to be annoyingly slow.
Now CherryPyWSGIServer
is used. An example of using the original
server is availble.
If set to True, tsapp does not append _public
or _private
to a bag when
pushing assets.
This option will also ensure use of the default tiddlyweb authentication
challenger when using the auth
command.
A URL prefix (without any /
)
prepended to /bags/<somebag>/tiddlers/<sometiddler>
that is used when
authenticating, looking up, pushing and deleting assets. This is limited
to just a single segment e.g. the prefix web
would complete the path as:
/web/bags/<somebag>/tiddlers/<sometiddler>
- http://tsapp.tiddlyspace.com/ provides a simple docs interface,
created with
tsapp
.
Thanks to @bengillies for his tsupload
script which provided some of the
motivation for creating this.