This is a short tutorial designed to get you started on writing Couchapps with evently and JS. I'm assuming you've read What the HTTP is Couchapp? so you understand how it works (things like 'files in your couchapp end up in a design document') but you just can't imagine how you're going to write your own small app.

The idea is to iteratively add functionality to a small app we'll be developing in this tutorial. This will let me introduce concepts one by one instead of everything at once so you'll be able to comprehend how this all works. I will be providing tarballs from time to time so you can debug your program from time to time, but really, the whole point here is to experiment by yourself. If you're asking yourself "what if I do this?", then you're going to learn quickly, since evently feels very natural after a few experiments. I'm not an evently expert and not a native english speaker : feel free to edit the tutorial to make it better, even if it's only typos.

Every command starting with $ is a command I'd like you to type to follow my explanations.

In the Beginning was the Hello World.

$ couchapp generate tutorial
$ cd tutorial
$ ls

Let's see what we have there:

Let's create our first file:

$ cd _attachments
$ cat > hello.html
<h1>Hello, world!</h1>
^D

This just means 'put Hello, world!' in hello.html, ^D meaning Control-D, which will mark the end of your file. Feel free to use something a bit less rough than cat to edit your files. So, how are we going to access to this file? Let's first push our app to CouchDB. If you don't have a .couchapprc file, add one under tutorial/.

$ couchapp push 
2010-09-16 10:46:56 [INFO] Visit your CouchApp here:
http://user:secretoass@localhost:5984/tutorial/_design/tutorial/index.html

Don't listen! Go to hello.html instead (you can specify "index":"hello.html" in couchapp.json if you want).

hello.html

This is different from this hello-world tutorial: we're just serving static html, not using a show function, even if the result is the same. Our hello.html is going to serve as a general structure for our widgets. I'm not using index.html on purpose so that you can understand what is going on.

Let's fill it up a bit more:

$ cat > hello.html
<!DOCTYPE html>
<html>
  <head>
    <title>Learning Couchapp, evently and mustache!</title>
    <link rel="stylesheet" href="style/main.css" type="text/css">
  </head>
  <body>
    <h1>Hello, World!</h1>
    <div id="items"><p>Empty items!</p></div>
    <div id="sidebar"><p>Empty sidebar!</p></div>
  </body>
</html>
^D

Hopefully, that's valid HTML. I've reused the div ids 'sidebar' and 'items' from the default app (see _attachments/index.html) just to get CSS for free: there is no special meaning. Also keep in mind that this is what search engines and noscript users will see: not much. That's not an inherent limitations of couchapps (see the CouchApp.org wiki source), but I'll only show you the 'all in js way' here, which is easier to learn the basics.

hello.html has become:

hello with css

Our first mustache

Now that we have our general structure, let's put some evently code in it, to bring some life to our page!

evently code lies in the evently/ folder and is going to be in charge of filling the divs with more useful content, maybe stuff from the database, or just dynamic forms and links. Each file or subfolder in evently/ will be a widget, and each file or subfolder in a widget folder will represent an event : _init is the default event, but you'll be able to create your own events easily. Since _init is called when loading the widget, we're going to write an _init event first.

$ cd evently/
$ ls
items profile
$ rm -rf items # we'll recreate an 'items' ourselves
$ mkdir items
$ cd items

_init will end up in the design document as JSON no matter how it is represented in items/, but in the meantime, you can specify it in your couchapp as you want:

The first option, _init.json, is the simplest way to create _init, and it will be pushed to CouchDB exactly like that. _init.js allows you to create a JS function that will be able to handle some logic, and _init will let you separate things a bit more, for example putting your template in a separate html file. We'll be doing that right now.

$ mkdir _init
$ cat > _init/mustache.html
<p>Items served via evently!</p>
^D

In every widget/event that will display stuff, you'll want to have a mustache component, which will be called via mustache.js, a template engine written in JS. We're not using any feature of mustache yet, since it is again static html, but don't skip the explanations here as they'll help you to understand how evently works.

Now that we have 'something useful' in items/mustache, let's call our code from hello.html. Add this at the end of hello.html between </body> and </html>.

<script src="vendor/couchapp/loader.js"></script>
<script type="text/javascript" charset="utf-8">
  $.couch.app(function(app) {
    $("#items").evently("items", app);
  });
</script>

We 'load' evently, and specify that '#items' should be loaded using items, which is our folder in evently. '#items' is just the jQuery selector that will match our items div.

$ couchapp push

items with evently

If everything went right, you'll see what I have in my screenshot. If something went wrong, look at tutorial-first-mustache.tar.gz to see what is different in your file tree.

Is everything really JSON?

Let's see. What if we don't have a _init/ folder, but just a _init.json file?

$ cd evently/
$ mv _init _init_backup
$ cat > _init.json
{
  "mustache" : "<p>_init is just json!</p>"
}
^D
$ couchapp push

items with _init.json

Good! Here is the associated archive. Feel free to experiment: how would you write _init.js?

You can now remove init.js/init.json and come back to the _init folder, that will give syntax highlighting for free in mustache.html.

Let's add a few events!

evently is all about events, so let's see how they are handled. There are two types of events: jQuery events like 'click', and custom events. I'm going to add a few links in the sidebar, and I'd like 'items' to show what link I clicked on. This a bit more complicated than the previous stuff, so I'll give less details. As always, I'll give the .tar.gz if you're unable to reproduce, but you should really try, that's the best way to learn.

Let's fill my sidebar with a few links. I'm going to make it an evently widget (currently it's rendered from hello.html) called 'choices' (life is all about those, after all).

Create evently/choices and then evently/choices/_init, and follow that up by creating evently/choices/_init/mustache.html containing the following

<p>You won a free topping! What would you like it to be?<p>
<ul>
  <li><a href="#cheese">Cheese</a></li>
  <li><a href="#bacon">Bacon</a></li>
  <li><a href="#chili">Chili</a></li>
  <li><a href="#tomatoes">Tomatoes</a></li>
</ul>

Add $("#sidebar").evently("choices", app); to _attachments/hello.html. couchapp push, F5, "oh, sidebar contains those links!". The next thing is to be able to catch the event of clicking on a link. This is a done with the 'selectors' object within an event.

$ cd choices/_init/
$ cat > selectors.json
{
  "a" : {"click": "function() { alert('click on a');}" }
}
^D

A selector object is a json object where each key will be some element on our page (here, all 'a' elements). The value will be another json object with a jquery event as a key ("click"), and what to do when this event is triggered. I decided here that I wanted to execute a function, but that's not the only possibility (we'll cover that later).

Now, when you click on a link, you get a superb alert window that informs you about it. Great! If it did not, try to see what's different from tutorial-first-event.tar.gz.

Note that you could also have your function in choices/_init/selectors/a/click.js, or even in choices/_init/selectors/a[href=#cheese]/click.js if you wanted to specify a different action on a specific link.

Anyway, now that I know evently know about the event, I'm going to ask him to route it to my 'items' widget. The first thing to do is to trigger a real evently event, which is done via 'trigger'. Since my function is becoming a bit more complicated, I'll move it in selectors/a/click.js and remove selectors.json.

Here is click.js:

function() {
  $(this).trigger('topping', 'cheese');
}

topping is the event, 'cheese' a parameter. I don't want it to always be cheese, but depends on the link I clicked! That's easy just change 'cheese' and put $(this).attr('href'). To make sure this really give you what you want, you can either debug with alert(), or, better, with $.log($(this).attr('href')) that will print in you console the object you gave him. In Chrome, that's Tools -> Javascript console, which you can also get with a right click -> Inspect element.

Now that the event is triggered, I need to receive it! Let's add a topping folder in items. Let's start by the mustache file:

<p>Oh, you want {{topping}} on your pizza!</p>

{{topping}} will get replaced by the real value of the topping by mustache. How can mustache know about that? We'll just have to pass it a json object like this one: {topping: "cheese"}. This is done in items/topping/data.js

function(e, topping) {
  return {topping : topping.slice(1)};
}

e is the event, topping the argument: we just return it as json, removing the first '#' with slice. We're nearly done!

Add $.evently.connect("#sidebar", "#items", ["topping"]); to hello.html: it just tells to evently that topping events should be routed from sidebar to items, and watch the magic happen.

So you want tomatoes?

If it did not work, check tutorial-connected-event.tar.gz.

Exercises

  1. A bit more state: save the list of choices the user has made. Use $$(this) for that.
  2. Pathbinder: #/cheese for example.
  3. Try decoupling the display and the 'event' handling: addToping.js and displayToppings/ in items, for example.

Don't miss part two: state!

Happy hacking!

Files attached to The 'Do It Yourself' Evently Tutorial: