Today I would like to talk about the couchapp tool. This is something that you can use when working on couchapps, and provides a way to quickly iterate your design.
However, rather confusingly, the couchapp tool isn't actually required for couchapps. If you get a design document with HTML attachments in to your database then you have a couchapp.
Why would you want to use such a tool then? Firstly because it will generate a skeleton couchapp for you, so that you don't have to remember how to organise it, and if it is your first couchapp it's good to start from something working.
More importantly though, the couchapp tool is useful as you develop as it allows you to edit the parts of your app in their native format. This means that if you are writing a HTML snippet you can just put some HTML in a file, rather than having to write it as part of a deeply nested JSON structure and deal with the errors that you would make if you did that. Also it means that you can use things like syntax highlighting in your preferred text editor without any special magic.
How it works
At it's core couchapp is a rather simple tool. It walks a filesystem tree and assembles the things that it finds there in to a JSON document.
For instance, if it finds a directory at the root of the tree called _attachments it puts the content of each file there in to a list which it puts in to the dict with an "_attachments" key, Which is one of the ways that couchdb accepts document attachments. Therefore if you have an _attachments/index.html file in your tree it will be attached to your design document when the JSON structure is sent to couchdb.
This continues across the tree, so the contents of the "views" directory will become the "views" key of the documents, which is how you do map/reduce queries on the database.
couchapp has various conventions for dealing with files. For instance if it finds a ".js" file it treats it as a javascript snippet which will be encoded in to a string in the resulting document. ".html" files outside of the "_attachments" directory will also be encoded as strings. If it finds a ".json" file then it treats it as literal JSON that will be embebedded.
This way it builds up the JSON structure that a couchapp expects, and will send it to the couchdb of your choice when it is done.
In addition to this functionality the tool can also generate you a skeleton app, and also add new pieces to your app, such as new views.
Getting It
couchapp is a python tool, so you can install it using pip or similar. However, Ubuntu users can install it from a PPA (yay for daily builds with recipes!).
Using It
To use it run
couchapp generate myapp
which will create you a new skeleton in myapp.
cd myapp ls
You will see for instance the _attachments and views directories, and an _attachments/index.html.
To get your app in to couchdb you can run
couchapp push http://localhost:5984/mydb
and it will tell you the URL to visit to see your new app.
If you want to use desktopcouch you can run
couchapp push desktopcouch://
though I think it has a bug that it prints the wrong URLs when pushing to desktopcouch.
Once you have looked at the HTML generated by your app you should look at the design document that couchapp created. Go to
http://localhost:5984/_utils
or
xdg-open ~/.local/share/desktop-couch/couchdb.html
if you are using desktopcouch.
Click to the mydb database and you will see a document called _design/myapp. Click on this and you will see the content of the design document; you are looking at a couchapp in its raw form.
If you compare what is in that design document with what is in the myapp directory that the tool created you should start to see how it generates it from the filesystem.
Now try making a change on the filesystem, for instance edit _attachments/index.html and put your name somewhere in the body. Then push again, running
couchapp push http://localhost:5984/mydb
and refresh the page in your browser and you should see the change. (Just click on index.html in the design document to get back to viewing your app from there).
I will go in to more detail about the content of the couchapp that was generated for you in another post.
See the previous installment.