refactor docs, make examples clearer

README

@@ -10,3 +10,9 @@ Release checklist:
 * Update version in config/application.yml
 * Push site
 * npm publish
+
+TODO:
+
+* Finish example_contacts.md
+* Change manager.md
+* Change modules.md

app/views/docs/ajax.md

@@ -155,13 +155,29 @@ When the server does return an unsuccessful response, an *ajaxError* event will
     Contact.bind "ajaxError", (record, xhr, settings, error) -> 
       # Invalid response...
       
-Likewise, when the server returns a successful response, an *ajaxSuccess* event will be fired on the record.
+Likewise, when the server returns a successful response, an *ajaxSuccess* event will be fired on the record, before it's updated.
 
     //= CoffeeScript
     contact.bind "ajaxSuccess", (status, xhr) -> 
       # Successful response...
+      
+However if you're designing your application correctly, you **shouldn't** ever need these events. Waiting for a server response goes against the whole concept of an asynchronous user interface. For example, if your server is returning extra data after a record has been created, Spine will automatically update the record with the new data. All you need to do is listen to the *save*, *update* or *change* events on the model. 
+
+    //= CoffeeScript
+    Contact.bind 'save', (contact) ->
+      alert("A contact was saved: #{contact.name}")
+      
+    contact = new Contact(name: 'Mr Async')
+    contact.bind 'save', (contact) ->
+      # Called twice, once on client-side save, 
+      # and once when the Ajax request completes
+      alert("A particular contact was saved: #{contact.name}")
+      
+    contact.save()
+
+There's no difference between a record being saved on the client side, and being saved in response to an Ajax request.
 
-If you need more control over event callbacks, you should use custom requests, as detailed in the next section. 
+If you need more control over Ajax event callbacks, you should use custom requests, as detailed in the next section. 
 
 ##Custom requests
 

app/views/docs/example2.md → app/views/docs/example_contacts.md

@@ -10,16 +10,35 @@ TODO
     cd contacts
     hem server
 
-##Generate models
+##Generate
 
     spine model contact
     spine controller contacts
+    spine controller contacts.main
+    spine controller contacts.sidebar
+
+##Contact model
+
+    Spine = require('spine')
+
+    class Contact extends Spine.Model
+      @configure 'Contact', 'name', 'email'
+
+      @extend @Local
+
+      @filter: (query) ->
+        return @all() unless query
+        query = query.toLowerCase()
+        @select (item) ->
+          item.name?.toLowerCase().indexOf(query) isnt -1 or
+            item.email?.toLowerCase().indexOf(query) isnt -1
+
+    module.exports = Contact
 
 ##Contacts controller
 
     Spine   = require('spine')
     Contact = require('models/contact')
-    Manager = require('spine/lib/manager')
     $       = Spine.$
 
     Main    = require('controllers/contacts.main')
@@ -52,15 +71,8 @@ TODO
 
     Spine   = require('spine')
     Contact = require('models/contact')
-    Manager = require('spine/lib/manager')
     $       = Spine.$
 
-    $.fn.serializeForm = ->
-      result = {}
-      for item in $(@).serializeArray()
-        result[item.name] = item.value
-      result
-
     class Show extends Spine.Controller
       className: 'show'
 
@@ -105,25 +117,17 @@ TODO
 
       submit: (e) ->
         e.preventDefault()
-        params = @form.serializeForm()
-        @item.updateAttributes(params)
+        @item.fromForm(@form).save()
         @navigate('/contacts', @item.id)
 
       delete: ->
         @item.destroy() if confirm('Are you sure?')
 
-    class Main extends Spine.Controller
-      className: 'main viewport'
-
-      constructor: ->
-        super
-        @show    = new Show
-        @edit    = new Edit
-
-        @manager = new Manager(@show, @edit)
-
-        @append @show, @edit
-
+    class Main extends Spine.Stack
+      controllers:
+        show: Show
+        edit: Edit
+
     module.exports = Main
 
 ##Contacts Sidebar