Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Collection of tools for making client side apps for TiddlySpace more easily.

branch: master

If we cannot guess the type of local file, fallback to JSON

This is an experimental feature that may need to be reverted
but it seems like it may be a useful hack.

In the past if the type could not be guessed we'd get an
error from the wsgi server. Now, intsead, fallback to application/json.

This makes it possible to drop JSON data files in the assets dir
for local testing. This can be useful when you want to load a tiddler
from local instead of remote. Usually we wouldn't expect these
files to get pushed. In fact the only way I've used it so far
is in a tsapp that _never_ gets pushed.
latest commit da08773c54
Chris Dent authored June 15, 2013
Octocat-spinner-32 script
Octocat-spinner-32 tsapp
Octocat-spinner-32 MANIFEST.in
Octocat-spinner-32 Makefile
Octocat-spinner-32 README
Octocat-spinner-32 README.md
Octocat-spinner-32 README.template
Octocat-spinner-32 readme.py
Octocat-spinner-32 setup.py
README.md

Summary

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.

Install

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.

Commands

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.

init

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.

serve

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.

push

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.

push_hard

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.

auth

tsapp auth <username>

Authenticate to the target_server as username and write the resulting auth token to the local directory's configuration file.

delete

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.

Configuration

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:

target_server

The URL (without trailing /) of the home tiddlyspace server. Defaults to http://tiddlyspace.com.

local_host

The hostname or IP to which to bind the local proxy. Default is 0.0.0.0.

port

The port to which to bind the local proxy. Default is 8080.

auth_token

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.

wsgi_sever

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.

tiddlyweb_mode

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.

server_prefix

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>

Examples

Acknowledgements

Thanks to @bengillies for his tsupload script which provided some of the motivation for creating this.

Something went wrong with that request. Please try again.