Yet more on docs.

CHANGELOG.md

@@ -1,14 +1,19 @@
 **v0.3.0 "The Gumbo Variations"** (unreleased):
 
-  - Changed: "magic locals" replaced by properties of `this` (`get` becomes `@get`). See #74 and `/docs/0.3-gumbo/announcement.md`.
-  - Backtraces show the relevant file and (js) file number.
-  - Normal JS scope restored: `def`, `zappa {foo}, ->` etc not needed anymore.
-  - Added the `'databag'` setting. Automatic input importing and exporting to templates now optional.
+  - Changed: "magic locals" replaced by properties of `this` (`get` becomes `@get`). See #74 and the [announcement](http://zappajs.org/docs/0.3-gumbo/announcement).
+
+  - Backtraces now show the relevant file and (js) file number.
+
+  - Normal JS scope restored: `def`, `zappa {foo}, ->` etc gone.
+
+  - Changed: automatic input "importing" and "exporting" to templates now optional through the `databag` setting. See #84.
 
 **v0.2.1** (2011-09-22):
 
   - Changed: using standard jquery from code.jquery.com instead of node-jquery. Updated to 1.6.4.
+
   - Changed: updated sammy to 0.7.0.
+
   - Fixed #80: Default layout is not being added correctly.
 
 **v0.2.0 "Peaches en Regalia"** (2011-09-08):

README.md

@@ -9,7 +9,7 @@
 
 # Node development for the lazy
 
-If you can describe it in 494 characters, why on earth should it take 879?
+If you can describe it in 495 characters, why on earth should it take 879?
 
 Zappa is a [CoffeeScript](http://coffeescript.org)-optimized interface to [Express](http://expressjs.com) and [Socket.IO](http://socket.io) that makes this:
 

docs/client.html

@@ -3,7 +3,6 @@
   <span class="nv">zappa.version = </span><span class="kc">null</span>
 
   <span class="nv">coffeescript_helpers = </span><span class="kc">null</span>
-  <span class="nv">copy_data_to = </span><span class="kc">null</span>
   <span class="nv">settings = </span><span class="kc">null</span>
 
   <span class="nv">zappa.run = </span><span class="nf">(func) -&gt;</span>
@@ -32,7 +31,11 @@
       <span class="nv">context.socket = </span><span class="nx">io</span><span class="p">.</span><span class="nx">connect</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">io</span><span class="p">,</span> <span class="nx">arguments</span>
 
     <span class="nv">context.emit = </span><span class="o">-&gt;</span>
-      <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="nx">emit</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">,</span> <span class="nx">arguments</span>
+      <span class="k">if</span> <span class="k">typeof</span> <span class="nx">arguments</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">isnt</span> <span class="s1">&#39;object&#39;</span>
+        <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="nx">emit</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">,</span> <span class="nx">arguments</span>
+      <span class="k">else</span>
+        <span class="k">for</span> <span class="nx">k</span><span class="p">,</span> <span class="nx">v</span> <span class="k">of</span> <span class="nx">arguments</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+          <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="nx">emit</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">,</span> <span class="p">[</span><span class="nx">k</span><span class="p">,</span> <span class="nx">v</span><span class="p">]</span>
 
     <span class="nv">route = </span><span class="nf">(r) -&gt;</span>
       <span class="nv">ctx = </span><span class="p">{</span><span class="nx">app</span><span class="p">}</span>
@@ -46,8 +49,10 @@
         <span class="nv">ctx.sammy_context = </span><span class="nx">sammy_context</span>
         <span class="nv">ctx.render = </span><span class="o">-&gt;</span> <span class="nx">sammy_context</span><span class="p">.</span><span class="nx">render</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">sammy_context</span><span class="p">,</span> <span class="nx">arguments</span>
         <span class="nv">ctx.redirect = </span><span class="o">-&gt;</span> <span class="nx">sammy_context</span><span class="p">.</span><span class="nx">redirect</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">sammy_context</span><span class="p">,</span> <span class="nx">arguments</span>
-        <span class="k">if</span> <span class="nx">settings</span><span class="p">[</span><span class="s1">&#39;autoimport&#39;</span><span class="p">]</span></pre></div>             </td>           </tr>                               <tr id="section-3">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-3">&#182;</a>               </div>               <p>Imports input vars to ctx. Does NOT overwrite existing variables.</p>             </td>             <td class="code">               <div class="highlight"><pre>          <span class="nx">copy_data_to</span> <span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">sammy_context</span><span class="p">.</span><span class="nx">params</span><span class="p">]</span>
-        <span class="nx">r</span><span class="p">.</span><span class="nx">handler</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span></pre></div>             </td>           </tr>                               <tr id="section-4">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-4">&#182;</a>               </div>               <p>GO!!!</p>             </td>             <td class="code">               <div class="highlight"><pre>    <span class="nx">func</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">context</span><span class="p">,</span> <span class="p">[</span><span class="nx">context</span><span class="p">])</span></pre></div>             </td>           </tr>                               <tr id="section-5">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-5">&#182;</a>               </div>               <p>Implements the websockets client with socket.io.</p>             </td>             <td class="code">               <div class="highlight"><pre>    <span class="k">if</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="o">?</span>
+        <span class="k">switch</span> <span class="nx">settings</span><span class="p">[</span><span class="s1">&#39;databag&#39;</span><span class="p">]</span>
+          <span class="k">when</span> <span class="s1">&#39;this&#39;</span> <span class="k">then</span> <span class="nx">r</span><span class="p">.</span><span class="nx">handler</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">sammy_context</span><span class="p">.</span><span class="nx">params</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span>
+          <span class="k">when</span> <span class="s1">&#39;param&#39;</span> <span class="k">then</span> <span class="nx">r</span><span class="p">.</span><span class="nx">handler</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">sammy_context</span><span class="p">.</span><span class="nx">params</span><span class="p">])</span>
+          <span class="k">else</span> <span class="nx">r</span><span class="p">.</span><span class="nx">handler</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span></pre></div>             </td>           </tr>                               <tr id="section-3">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-3">&#182;</a>               </div>               <p>GO!!!</p>             </td>             <td class="code">               <div class="highlight"><pre>    <span class="nx">func</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">context</span><span class="p">,</span> <span class="p">[</span><span class="nx">context</span><span class="p">])</span></pre></div>             </td>           </tr>                               <tr id="section-4">             <td class="docs">               <div class="pilwrap">                 <a class="pilcrow" href="#section-4">&#182;</a>               </div>               <p>Implements the websockets client with socket.io.</p>             </td>             <td class="code">               <div class="highlight"><pre>    <span class="k">if</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="o">?</span>
       <span class="k">for</span> <span class="nx">name</span><span class="p">,</span> <span class="nx">h</span> <span class="k">of</span> <span class="nx">ws_handlers</span>
         <span class="nx">do</span> <span class="nf">(name, h) -&gt;</span>
           <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="kc">on</span> <span class="nx">name</span><span class="p">,</span> <span class="nf">(data) -&gt;</span>
@@ -56,25 +61,24 @@
               <span class="nv">socket: </span><span class="nx">context</span><span class="p">.</span><span class="nx">socket</span>
               <span class="nv">id: </span><span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="nx">id</span>
               <span class="nv">data: </span><span class="nx">data</span>
-              <span class="nv">emit: </span><span class="o">-&gt;</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="nx">emit</span><span class="p">.</span><span class="nx">apply</span> <span class="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">,</span> <span class="nx">arguments</span>
-
-            <span class="k">if</span> <span class="nx">settings</span><span class="p">[</span><span class="s1">&#39;autoimport&#39;</span><span class="p">]</span>
-              <span class="nx">copy_data_to</span> <span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">data</span><span class="p">]</span>
+              <span class="nv">emit: </span><span class="nx">context</span><span class="p">.</span><span class="nx">emit</span>
 
             <span class="k">for</span> <span class="nx">name</span><span class="p">,</span> <span class="nx">helper</span> <span class="k">of</span> <span class="nx">helpers</span>
               <span class="nx">do</span> <span class="nf">(name, helper) -&gt;</span>
                 <span class="nx">ctx</span><span class="p">[</span><span class="nx">name</span><span class="p">]</span> <span class="o">=</span> <span class="o">-&gt;</span>
                   <span class="nx">helper</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="nx">arguments</span><span class="p">)</span>
 
-            <span class="nx">h</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span>
+            <span class="k">switch</span> <span class="nx">settings</span><span class="p">[</span><span class="s1">&#39;databag&#39;</span><span class="p">]</span>
+              <span class="k">when</span> <span class="s1">&#39;this&#39;</span> <span class="k">then</span> <span class="nx">h</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">data</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span>
+              <span class="k">when</span> <span class="s1">&#39;param&#39;</span> <span class="k">then</span> <span class="nx">h</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">data</span><span class="p">])</span>
+              <span class="k">else</span> <span class="nx">h</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="nx">ctx</span><span class="p">,</span> <span class="p">[</span><span class="nx">ctx</span><span class="p">])</span>
 
     <span class="nx">$</span><span class="p">(</span><span class="o">-&gt;</span> <span class="nx">app</span><span class="p">.</span><span class="nx">run</span> <span class="s1">&#39;#/&#39;</span><span class="p">)</span> <span class="k">if</span> <span class="nx">app</span><span class="o">?</span>
 
-<span class="vi">@build = </span><span class="nf">(version, coffeescript_helpers, copy_data_to, settings) -&gt;</span>
+<span class="vi">@build = </span><span class="nf">(version, coffeescript_helpers, settings) -&gt;</span>
   <span class="nb">String</span><span class="p">(</span><span class="nx">skeleton</span><span class="p">)</span>
     <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="s1">&#39;version = null;&#39;</span><span class="p">,</span> <span class="s2">&quot;version = &#39;#{version}&#39;;&quot;</span><span class="p">)</span>
     <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="s1">&#39;coffeescript_helpers = null;&#39;</span><span class="p">,</span> <span class="s2">&quot;var coffeescript_helpers = &#39;#{coffeescript_helpers}&#39;;&quot;</span><span class="p">)</span>
-    <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="s1">&#39;copy_data_to = null;&#39;</span><span class="p">,</span> <span class="s2">&quot;var copy_data_to = #{copy_data_to};&quot;</span><span class="p">)</span>
     <span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="s1">&#39;settings = null;&#39;</span><span class="p">,</span> <span class="s2">&quot;var settings = #{JSON.stringify settings};&quot;</span><span class="p">)</span>
 
 </pre></div>             </td>           </tr>                </tbody>     </table>   </div> </body> </html> 

docs/crashcourse.md

@@ -120,7 +120,7 @@ Right. This is what a basic route with a handler function looks like:
 
 As you can see, the value of `this` is modified in the handler function too, giving you quick access to everything you need to handle the request. The low level API lives at `@request`, `@response` and `@next`, but you also have handy shortcuts such as `@render`, `@redirect`, `@query`, `@params`, etc.
 
-Of course, you can use an alternative reference here too:
+Of course, you can receive the context as a param here too:
 
 {% highlight coffeescript %}
 @get '/:name': (foo) ->
@@ -132,21 +132,22 @@ If you return a string, it will automatically be sent as the response. But most
 {% highlight coffeescript %}
 @get '/ponchos/:id': ->
   Poncho.findById @params.id, (err, poncho) =>
+    # Is that a real poncho, or is that a sears poncho?
     @send poncho.type
 {% endhighlight %}
 
 Note that we're using a fat arrow (`=>`) here, to preserve the value of `this`. We could be just as well using the alternative reference (`foo.send`) and a normal arrow.
 
 ## Radical views
 
-Generally `@render` works just as `@response.render`:
+Generally `@render` works just like `@response.render`:
 
 {% highlight coffeescript %}
 @get '/': ->
   @render 'index', foo: 'bar'
 {% endhighlight %}
 
-One difference is that it also accepts an object as parameter:
+One difference is that it also works with the "key: value syntax":
 
 {% highlight coffeescript %}
 @get '/': ->
@@ -172,7 +173,7 @@ Another is that you can define inline views that `@render` "sees" as if they wer
     body @body
 {% endhighlight %}
 
-Note that zappa comes with a default templating engine, [CoffeeKup](http://coffeekup.org), and you don't have to setup anything to use it. You can also easily use other templating engines through the mechanisms express provides, inline templates and all.
+Note that zappa comes with a default templating engine, [CoffeeKup](http://coffeekup.org), and you don't have to setup anything to use it. You can also easily use other engines by specifying the file extension or the `'view engine'` setting; it's just express. Well, express + inline views support:
 
 {% highlight coffeescript %}
 
@@ -196,7 +197,7 @@ Note that zappa comes with a default templating engine, [CoffeeKup](http://coffe
 '''
 
 @view 'index.jade': '''
-  - title = 'Jade template';
+  - title = "Jade template";
   h1= title
   p= foo
 '''
@@ -225,7 +226,7 @@ require('zappa') ->
     p @foo
 {% endhighlight %}
 
-It's just as if you had also written the following:
+The following template will be added automatically:
 
 {% highlight coffeescript %}
 @view layout: ->
@@ -262,9 +263,13 @@ require('zappa') ->
     @broadcast shouted: {@id, text: @data.text}
 {% endhighlight %}
 
-With the client-side zappa API (see below), you can use the same style on the browser too.
+Socket.io is automatically required and attached to the express server, intercepting WebSockets/comet traffic on the same port.
 
-## Client-side code
+Just like in request handlers, the value of `this` is modified to include all the relevant stuff you need, including the low-level API (here at `@socket` and `@io`) and smart shortcuts (`@id`, `@emit`, `@broadcast`, etc). Input variables are available at `@data`.
+
+On the client-side, you can use the vanilla socket.io API if you like, but that wouldn't make much sense, would it? Which leads us to...
+
+## The client side of the source
 
 With `@coffee`, you can define client-side code inline, and serve it in JS form with the correct content-type set. No compilation involved, since we already have its string representation from the runtime:
 
@@ -437,4 +442,10 @@ Finally, when using strings and objects, zappa will intercept some specific midd
 
 # Syntactic sugar for:
 @app.use @express.static(__dirname + '/public')
-{% endhighlight %}
+{% endhighlight %}
+
+## Aaaaaand that's it for tonight.
+
+Thank you for coming to the show, hope you enjoyed it. [CoffeeScript](https://coffeescript.org) on guitar, [Express](http://expressjs.com) on the keyboards, [Socket.IO](http://socket.io) on drums. [Node.js](http://nodejs.org) on background vocals, [npm](http://npmjs.org) on bass. G'night everyone.
+
+To learn more, check out [the links](http://zappajs.org) at the home page.