Permalink
Browse files

Yet more on docs.

  • Loading branch information...
1 parent da1be70 commit b08b28e37e91e616cdeab3727761e1f73914d330 @mauricemach mauricemach committed Sep 29, 2011
Showing with 101 additions and 55 deletions.
  1. +9 −4 CHANGELOG.md
  2. +1 −1 README.md
  3. +15 −11 docs/client.html
  4. +20 −9 docs/crashcourse.md
  5. +55 −29 docs/zappa.html
  6. +1 −1 index.md
View
@@ -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):
View
@@ -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:
View
@@ -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>
View
@@ -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.
Oops, something went wrong.

0 comments on commit b08b28e

Please sign in to comment.