Permalink
Browse files

Documentation updates.

  • Loading branch information...
shimaore committed Aug 26, 2012
1 parent e8f913b commit f29f879a0cf00c9919a5a00ab85d7294ea847815
Showing with 116 additions and 44 deletions.
  1. +1 −1 benchmarks/express.coffee
  2. +1 −1 docs/client.html
  3. +2 −1 docs/migrate-0.4.md
  4. +91 −30 docs/reference.md
  5. +19 −9 docs/zappa.html
  6. +1 −1 package.json
  7. +1 −1 src/zappa.coffee
@@ -1,4 +1,4 @@
-app = require('express').createServer()
+app = require('express')()
fs = require 'fs'
compile = require('coffeecup').adapters.express.compile
View
@@ -64,7 +64,7 @@
<span class="k">when</span> <span class="s">&#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="nx">context</span><span class="p">.</span><span class="nx">socket</span><span class="p">.</span><span class="kc">on</span> <span class="s">&#39;connect&#39;</span><span class="p">,</span> <span class="o">-&gt;</span>
- <span class="nx">context</span><span class="p">.</span><span class="nx">share</span> <span class="s">&#39;__local&#39;</span><span class="p">,</span> <span class="nx">socket</span><span class="p">,</span> <span class="nf">(data) -&gt;</span>
+ <span class="nx">context</span><span class="p">.</span><span class="nx">share</span> <span class="s">&#39;__local&#39;</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="nf">(data) -&gt;</span>
<span class="nv">context.key = </span><span class="nx">data</span><span class="p">.</span><span class="nx">key</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>
View
@@ -23,7 +23,8 @@ Zappa in places. Here are the differences we know about.
This will require that you have the `zappa-partials` module installed in
your application. (This module is an extended version of
- `express-partials`.)
+ `express-partials` with support for multiple instances, pending integration
+ in mainline.)
* Express 3.0 is no longer a subclass of the Node.js HTTP server. The server
object is available as `@server`; `@app.listen` is now
View
@@ -1,6 +1,6 @@
----
+--
layout: default
-title: API Reference (v0.4.0)
+title: API Reference (v0.4.8)
permalink: /reference/index.html
---
@@ -28,7 +28,7 @@ Returns an object with attributes `id` (uuid generated by zappa for this app), `
`zappa.run [port,] [host,] [options,] function`
-Same as `zappa.app`, but calls `app.listen` for you.
+Same as `zappa.app`, but calls `server.listen` for you.
It will automatically print the equivalent to the following to stdout:
@@ -43,14 +43,14 @@ The base export is actually a reference to this same function, so these are equi
require('zappajs') ->
@get '/': 'hi'
-You can pass the parameters in any order. Number is port, string is host, object is options, and function is your application. Port and host are optional. Omitted params will also be omitted in the `app.listen` call to express (defaulting to port 3000 and binding to `INADDR_ANY`).
+You can pass the parameters in any order. Number is port, string is host, object is options, and function is your application. Port and host are optional. Omitted params will also be omitted in the `server.listen` call to express (defaulting to port 3000 and binding to `INADDR_ANY`).
You can also pass the parameters in the `options` object. The following options are available:
* `port`
* `host`
* `disable_io`: if true, the Socket.IO interface will be disabled.
-* `css`: an array of CSS template modules names, or a string containing a single CSS template module name. Defaults to `["stylus"]`.
+* `css`: an array of CSS template modules names, or a string containing a single CSS template module name. Defaults to `["stylus"]` for backward-compatibility.
require('zappajs') css:'less', ->
@less '/index.css': 'body { color: black }'
@@ -63,7 +63,18 @@ You can also pass the parameters in the `options` object. The following options
### zappa.adapter
-Creates a zappa view adapter to be used with `@register`. See `@view`.
+`zappa.adapter engine[, options]`
+
+Creates a zappa view adapter that can be provided to `@engine` or `@use partials:`.
+This view adapter complies with both Express 2.x (`render`,`compile`) and Express 3.x specifications.
+
+The `engine` might be a string (in which case it is passed to `require` first) or an engine object (in which case it must provide a `compile` method).
+
+The view adapter provides the content of `params` at the root of the template's dataset, except for those whose name is listed in `options.blacklist`. For example, the default zappa adapter is:
+
+ zappa.adapter 'coffeecup', blacklist: ['format', 'autoescape', 'locals', 'hardcode', 'cache']
+
+See `@view` for more details.
## ROOT SCOPE
@@ -96,7 +107,7 @@ Ex.:
@get
'/': -> 'hi'
'/wiki': 'wiki'
- '/chat': -> response.send 'chat'
+ '/chat': -> @response.send 'chat'
# Route Middleware example
load_user = ->
@@ -121,6 +132,8 @@ The handler functions will have access to all variables described in the **socke
### @helper
+Helpers content is made available to both the request handler and sockets handler scopes.
+
`@helper name: data`
The helper will provide the associated data.
@@ -162,7 +175,7 @@ Ex.:
<h1><%= @foo %></h1>
'''
-By default, the templating engine is CoffeeCup. To use other engines, just use express' mechanisms:
+By default, the templating engine is CoffeeCup with extension `.coffee`. To use other engines, just use express' mechanisms:
@render 'index.jade'
@@ -179,7 +192,7 @@ Since in express templating data is usually mixed up with framework locals and t
To use this feature with other templating engines:
blacklist = 'scope self locals filename debug compiler compileDebug inline'.split ' '
- @register jade: @zappa.adapter 'jade', blacklist
+ @engine jade: @zappa.adapter 'jade', blacklist
To disable it on default zappa:
@@ -291,15 +304,15 @@ Serves `";#{coffeescript_helpers}(#{your_function})();"` as `/foo.js`, with cont
Serves the string as `/foo.js`, with content-type `application/javascript`.
-### @css
+### @css (string)
@css '/foo.css': '''
body { font-family: sans-serif; }
'''
Serves the string as `/foo.css`, with content-type `text/css`.
-### @css
+### @css (function)
border_radius = (radius)->
WebkitBorderRadius: radius
@@ -368,7 +381,7 @@ Note: Any other CSS template module that provides a `.render` method might be us
### @zappa
-The same object that is exported when you `require 'zappa'`. See the "exports" section.
+The same object that is exported when you `require 'zappa'`.
### @express
@@ -380,7 +393,7 @@ The object returned by `require('socket.io').listen`.
### @app
-The object returned by `express.createServer`.
+The object returned by `express()`.
### @use
@@ -402,16 +415,32 @@ When passing strings and objects, zappa's own middleware will be used if availab
Currently available zappa middleware are:
-#### 'static'
+#### `'static'`
Same as `@express.static(root + '/public')`, where `root` is the directory of the first file that required zappa.
-#### 'zappa'
+#### `'zappa'`
Serves `/zappa/Zappa.js`, `/zappa/zappa.js`, `/zappa/jquery.js` and `/zappa/sammy.js`. Automatically added by `@client` and `@shared` if not added before.
To minimize page download delay on the client, use `/zappa/Zappa.js`, which combines Zappa, jQuery, Sammy.js, and Socket.IO client-side scripts into a single download.
+#### `'partials'`
+
+Uses `zappajs-partials` (aka `express-partials`) to bring back layout and partials support to Express 3.x.
+
+Since Express 3.x requires asynchronous template engines, but partials require synchronous template engines, if you provided any non-standard mappings to express via `@engine` you will need to provide these as well to partials:
+
+ # Our '.html' files are actually jade files.
+ @use partials:
+ html: @zappa.adapter 'jade'
+
+As with `@engine`, this is not required if the file extension matches the template engine name, and the `.coffee` extension is already mapped to CoffeeCup.
+
+#### `session_store`
+
+The same session store object you passed to Express in `@use session:` ; required if you want to be able to use `@session` from within a sockets handler scope.
+
### @configure
Shortcut to `@app.configure`. Accepts an object as param. Ex.:
@@ -438,20 +467,24 @@ Shortcut to `@app.disable`. Accepts multiple params in one go. Ex.:
@disable 'foo', 'bar'
-### @register
+### @engine
Similarly to Express `@app.engine`, allows to register specific template engines.
This is normally not needed unless you want to change the behavior of the engine, for example to benefit from `zappa.adapter`.
Accepts an object as param. Ex.:
- @register eco: require 'eco'
+ @engine eco: require 'eco'
+
+Note that most template engines do not support the new Express 3.x conventions at this time, if you want to use them with Zappa you should either register them as shown above:
+
+ blacklist = 'scope self locals filename debug compiler compileDebug inline'.split ' '
+ @engine jade: @zappa.adapter 'jade', blacklist
-Note that most template engines do not support the new Express 3.x conventions at this time, if you want to use them with Zappa you should either register them as shown above,
or use the [consolidate](https://github.com/visionmedia/consolidate.js) package:
- @app.engine 'eco', require('consolidate').eco
+ @engine 'eco', require('consolidate').eco
## REQUEST HANDLERS SCOPE
@@ -477,25 +510,34 @@ Directly from express.
Shortcut to `@request.query`
+The parameters listed after `?` in the URI.
+
### @body
Shortcut to `@request.body`
+This might be the raw body or a parsed body if you `@use 'bodyParser'` .
+
### @params
Shortcut to `@request.params`
+The parameters found in the URI path, for example
+
+ @get '/user/:name', ->
+ @params.name
+
### @session
Shortcut to `@request.session`
### @send
-Shortcut to `@response.send`.
+Shortcut to `@response.send`
### @render
-Shortcut to `@response.render`.
+Shortcut to `@response.render`
Adds the following features:
@@ -505,10 +547,22 @@ Adds the following features:
- You can use post-rendering (see `@postrender`): `render 'index', postrender: 'foo'`.
- - You can use layouts: `render 'index', layout:'layout'`. The default layout is called `layout` and is active by default. To disable layout processing: `render 'index', layout: no`.
-
- If the setting `databag` is on, the databag will be automatically available to templates as `params`.
+ - You can use layouts and partials (even though Express 3.x no longer provides them):
+
+ @use 'partials'
+ @get '/': ->
+ @render 'index', layout:'layout'
+
+ You may `@enable 'default layout' to activate the default layout; or provide your own:
+
+ @view layout: ->
+ html ->
+ body: @body
+
+ To disable layout processing: `@render 'index', layout: no`.
+
### @redirect
Shortcut to `@response.redirect`.
@@ -549,47 +603,54 @@ An empty object unique for each socket. You can put data pertaining to the clien
### @emit
-Shortcut to `socket.emit`. Send a message to the client.
+Shortcut to `@socket.emit`. Send a message to the client.
Adds the following features:
- You can use the syntax: `@emit name: {foo: 'bar'}`.
### @broadcast
-Shortcut to `socket.broadcast`. Send a message to all clients except ours.
+Shortcut to `@socket.broadcast`. Send a message to all clients except ours.
+
+Adds the following features:
- You can use the syntax: `@broadcast name: {foo: 'bar'}`.
### @join (room)
-Shortcut to `socket.leave`.
+Shortcut to `@socket.join`.
### @leave (room)
-Shortcut to `socket.leave`.
+Shortcut to `@socket.leave`.
### `@broadcast_to` (room,...)
+Shortcut to `@io.sockets.in(room).emit`.
+
Broadcast to a room.
### `@session (error,session) ->`
Gets the associated Express session.
-The session object is only available if the Express session was previously linked to the socket using client-side `@share`.
+The session object is only available if the Express session was previously linked to the socket using client-side `@share` *and* you `@use session_store:` to give the socket handler access to the Express session store.
This is done automatically for the default, local Express session and local Socket.IO server.
-See `examples/share_*.coffee` for a complete example.
+See `examples/share_*.coffee` for a complete example using separate servers for Socket.IO and Express.
## VIEW SCOPE
-The normal view scope is a [CoffeeCup scope](https://github.com/gradus/coffeecup/blob/master/docs/reference.md#the-template-scope).
+The normal view scope is a [CoffeeCup scope](https://github.com/gradus/coffeecup/blob/master/docs/reference.md#the-template-scope)
+extended via `zappa.adapter` (so that `@foo === @params.foo`).
## CLIENT-SIDE ROOT SCOPE
This is the scope inside a `@client` or `@shared` callback.
+
+
### @app
The Sammy.js application, if Sammy is present.
Oops, something went wrong.

0 comments on commit f29f879

Please sign in to comment.