API Reference (v0.3.1)

Please note this is a work in progress. There are still many sections to be added or refined.

EXPORTS

require 'zappa' returns a function with the following attributes:

zappa.version

Version of zappa running. Ex.: 0.3.1.

If you’re running a version not released on npm (directly from the repo), it will have edge appended to it. Ex.: 0.3.1edge.

zappa.app

zappa.app [locals,] function

Builds an app with express/socket.io, based on the function you provided.

This function will be called with the value of this/@ set to an object with all the attributes described in the root scope section.

Returns an object with attributes id (uuid generated by zappa for this app), app (express server) and io (socket.io server).

zappa.run

zappa.run [port,] [host,] [locals,] function

Same as zappa.app, but calls app.listen for you.

The base export is actually a reference to this same function, so these are equivalent:

require('zappa').run ->
  @get '/': 'hi'
  
require('zappa') ->
  @get '/': 'hi'

You can pass the parameters in any order. Number is port, string is host, 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).

It will automatically print the equivalent to the following to stdout:

Express server listening on port xxxx in [development/production] mode
Zappa x.x.x orchestrating the show

zappa.adapter

Creates a zappa view adapter to be used with @register. See @view.

ROOT SCOPE

The function you pass to zappa.app or zappa.run will be called with this/@ set to an object with the following attributes:

@get, @post, @put, @del

@get '/path': handler

Define handlers for HTTP requests.

Shortcuts to express’ app.[verb]. Params will just be passed forward unmodified (except for the handler function, which will be re-scoped), unless a single object is passed. In which case, each key in the object will be a route path, and the value its respective handler. The handler can be a function or a string. In the latter case, the handler passed to express will be a function that only calls res.send with this string.

The handler functions will have access to all variables described in the HTTP handlers scope section.

If a handler returns a string, res.send(string) will be called automatically.

Ex.:

@get '/': 'hi'

@get '/', -> 'hi'

@get /regex/, -> 'hi'

@get '/': 'hi', '/wiki': 'wiki', '/chat': 'chat'

@get
  '/': -> 'hi'
  '/wiki': 'wiki'
  '/chat': -> response.send 'chat'

@on

@on event: handler

Define handlers for events emitted by the client through socket.io.

Shortcut to socket.io’s socket.on 'event'.

The handler functions will have access to all variables described in the Socket.io handlers scope section. They won’t have access to their parent scope. To make variables available to these handlers, use def or helper.

@helper

@helper name: function

A function that will be available to both the HTTP and sockets scopes. It will have access to the same variables as whatever called it. Ex.:

@get '/': ->
  @sum 5, 7
  
@on connection: ->
  @sum 26, 18

@helper sum: (a, b) ->
                        # Values when called from `@get` vs `@on`
  console.log a         # 5 vs 26
  console.log @request  # available vs undefined
  console.log @emit     # undefined vs available

Since the parameter is actually an object, you can define any number of helpers in one go:

@helper
  @sum: (a, b) -> a + b
  @subtract: (a, b) -> a - b

@view

@view path: contents

Define an inline template. For all purposes it’s like you had a file on disk at path. It will have precedence over a template on disk.

Ex.:

@view index: ->
  h1 @foo
  
@view 'index.eco': '''
  <h1><%= @foo %></h1>
'''

By default, the templating engine is CoffeeKup. To use other engines, just use express’ mechanisms:

@render 'index.jade'

Or:

@set 'view engine': 'jade'

All variables at @/params (request params + those you created) are automatically made available to templates as params.foo (in CoffeeKup, @params.foo).

In addition, if you’re using the zappa view adapter (as is the case by default, with CoffeeKup), they’re also made available at the template’s “root namespace” (foo or CoffeeKup’s @foo).

Since in express templating data is usually mixed up with framework locals and template options, the adapter will only put variables in the template root if there isn’t a variable there with the same name already, and the name is not blacklisted.

To use this feature with other templating engines:

blacklist = 'scope self locals filename debug compiler compileDebug inline'.split ' '
@register jade: @zappa.adapter 'jade', blacklist

To disable it on default zappa:

@register coffee: require('coffeekup').adapters.express

@postrender

@postrender name: function

DOM rendering with server-side jQuery. Defines a function that can be applied after @render.

To use this feature, npm install jsdom first.

@postrender plans: ($) ->
  $('.staff').remove() if @user.plan isnt 'staff'
  $('div.' + @user.plan).addClass 'highlighted'

@get '/postrender': ->
  @user = plan: 'staff'
  @render index: {postrender: 'plans'}

It receives an alternative reference to the context as an optional last parameter:

@postrender plans: ($, foo) ->
  $('.staff').remove() if foo.user.plan isnt 'staff'

@include

@include file

Will require the file at the path specified, and run a function exported as include against the same scope as the current function. Ex.:

# app.coffee
require('zappa') ->
  @foo = 'bar'
  ping = 'pong'
  @get '/': 'main'
  @include './sub'
  
# sub.coffee
@include = ->
  console.log @foo    # 'bar'
  console.log ping    # error
  get '/sub': 'sub'

@client

@client '/foo.js': ->
  sum = (a, b) -> a + b
  
  @helper foo: (param) ->
    console.log param                       # 'bar' or 'pong'
    sum 1, 2                                # 3
    console.log @zig                        # A request or event input param.
    if @render? then console.log 'route'
    else if @emit? then console.log 'event'

  @get '#/': ->
    @foo 'bar'
    console.log 'A client-side route.'
    
  @on welcome: ->
    @foo 'pong'
    console.log 'A socket.io event.'

Serves ";zappa.run(#{your_function});" as /foo.js, with content-type application/javascript.

To use it, you must also include /zappa/zappa.js in your template, before /foo.js.

@shared

@shared '/index.js': ->
  sum = (a, b) -> a + b

  @helper role: (name) ->
    unless @user.role is name
      if @request? then @redirect '/login'
      else if window? then alert "This is not the page you're looking for."
      else if @socket? then client.disconnect()

@get '/admin': ->
  @role 'admin'
  # admin stuff

@on 'delete everything': ->
  @role 'admin'

@client '/index.js': ->
  @get '#/admin': ->
    @role 'admin'
    # admin stuff

Same as @client, but also makes the elements defined in the function available at the server-side.

@coffee

@coffee '/foo.js': ->
  alert 'hi!'

Serves ";#{coffeescript_helpers}(#{your_function})();" as /foo.js, with content-type application/javascript.

@js

@js '/foo.js': '''
  alert('hi!');
'''

Serves the string as /foo.js, with content-type application/javascript.

@css

@css '/foo.css': '''
  font-family: sans-serif;
'''

Serves the string as /foo.css, with content-type text/css.

@stylus

@stylus '/foo.css': '''
  border-radius()
    -webkit-border-radius arguments  
    -moz-border-radius arguments  
    border-radius arguments  

  body
    font 12px Helvetica, Arial, sans-serif  

  a.button
    border-radius 5px
'''

Compiles the string with stylus and serves the results as /foo.css, with content-type text/css.

You must have stylus installed with npm install stylus.

@zappa

The same object that is exported when you require 'zappa'. See the “exports” section.

@express

The object returned by require 'express'.

@io

The object returned by require('socket.io').listen.

@app

The object returned by express.createServer.

@use

Shortcut to @app.use. It can be used in a number of additional ways:

It accepts multiple params. Ex.:

@use express.bodyParser(), @app.router, express.cookies()

It accepts strings as parameters. This is syntactic sugar to the equivalent express middleware with no arguments. Ex.:

@use 'bodyParser', @app.router, 'cookies'

You can also specify parameters by using objects. Ex.:

@use 'bodyParser', static: __dirname + '/public', session: {secret: 'fnord'}, 'cookies'

Finally, when using strings and objects, zappa will intercept some specific middleware and add behaviour, usually default parameters. Ex.:

@use 'static'

# Syntactic sugar for:
@app.use @express.static(__dirname + '/public')

@configure

Shortcut to @app.configure. Accepts an object as param. Ex.:

@configure
  development: => @use 'foo'
  production: => @use 'bar'

@set

Shortcut to @app.set. Accepts an object as param. Ex.:

@set foo: 'bar', ping: 'pong'

@enable

Shortcut to @app.enable. Accepts multiple params in one go. Ex.:

@enable 'serve jquery', 'serve sammy'

@disable

Shortcut to @app.disable. Accepts multiple params in one go. Ex.:

@disable 'serve jquery', 'serve sammy'

@register

Shortcut to @app.register. Accepts an object as param. Ex.:

@register eco: require 'eco'

Note that while @app.register '.eco' uses a dot, @register eco doesn’t.

REQUEST HANDLERS SCOPE

@response

Directly from express.

@request

Directly from express.

@next

Directly from express.

@query

Shortcut to @request.query

@body

Shortcut to @request.body

@params

Shortcut to @request.params

@session

Shortcut to @request.session

@send

Shortcut to @response.send.

@render

Shortcut to @response.render.

Adds the following features:

- You can use the syntax: @render name: {foo: 'bar'}.

- You can use inline views (see @view).

- You can use postrenders: render 'index', postrender: 'foo'.

- If the setting databag is on, the databag will be automatically available to templates as params.

@redirect

Shortcut to @response.redirect.

SOCKETS HANDLERS SCOPE

@socket

Directly from socket.io.

@data

Directly from socket.io.

@id

Shortcut to @socket.id.

@client

An empty object unique for each socket. You can put data pertaining to the client here, as an alternative to @socket.set.

@emit

Shortcut to socket.emit.

Adds the following features:

- You can use the syntax: @emit name: {foo: 'bar'}.

@broadcast

Shortcut to socket.broadcast.

- You can use the syntax: @broadcast name: {foo: 'bar'}.

VIEW SCOPE

CLIENT-SIDE ROOT SCOPE

@get, @post, @put, @del

Routes with sammy.js.

@on

Event handlers with socket.io.

@helper

Same as its server-side counterpart.

CLIENT-SIDE ROUTE HANDLERS SCOPE

CLIENT-SIDE SOCKETS HANDLERS SCOPE

APP SETTINGS

You can use the following options with @set, @enable and @disable:

‘serve zappa’

Serves /zappa/zappa.js, required to use the zappa client API. Automatically enabled by client and shared.

‘serve jquery’

Serves /zappa/jquery.js (just standard, minified jQuery).

‘serve sammy’

Serves /zappa/sammy.js (just standard, minified Sammy).

‘minify’

Uses uglify-js to minify the outputs of serve zappa, client, shared, coffee and js.

‘default layout’

If enabled, zappa adds the following template with the name layout:

doctype 5
html ->
  head ->
    title @title if @title
    if @scripts
      for s in @scripts
        script src: s + '.js'
    script(src: @script + '.js') if @script
    if @stylesheets
      for s in @stylesheets
        link rel: 'stylesheet', href: s + '.css'
    link(rel: 'stylesheet', href: @stylesheet + '.css') if @stylesheet
    style @style if @style
  body @body

‘databag’

Values: this or param.

When this:

@get '/:foo': (c) ->
  @foo += '!'
  c.render 'index'

When param:

@get '/:foo': (c) ->
  c.foo += '!'
  @render 'index'