Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added an initial version of the website.

  • Loading branch information...
commit bbc62c2502b35bf0594a82403c24648c3c71bef9 1 parent dbbd11f
@mauricemach mauricemach authored
View
3  .gitignore
@@ -4,4 +4,5 @@ node_modules/
lib/*.js
benchmarks/out/*.dat
benchmarks/out/*.out
-tests/*.js
+tests/*.js
+_site
View
1  .npmignore
@@ -1,2 +1,3 @@
.git*
material/
+_site
View
1  CNAME
@@ -0,0 +1 @@
+zappajs.org
View
1  _config.yml
@@ -0,0 +1 @@
+source: docs
View
99 docs/_layouts/default.html
@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Zappa: {{page.title}}</title>
+ <link rel="stylesheet" href="/css/highlight.css">
+ <style>
+ html, body {
+ margin: 0;
+ padding: 0;
+ color: #999;
+ font-family: Lucida Grande, sans-serif;
+ font-size: 18px;
+ }
+
+ html {
+ background-color: #000;
+ background-image: url(/images/zappa.png);
+ background-repeat: no-repeat;
+ background-attachment: fixed;
+ background-size: auto 100%;
+ }
+
+ h1, h2, h3, h4, h5, h6 {
+ font-family: Georgia;
+ font-weight: normal;
+ color: #fff;
+ margin-left: -20px;
+ }
+
+ h1 {font-size: 38px}
+ h2 {font-size: 32px}
+ h3 {font-size: 28px}
+ h4 {font-size: 24px}
+
+ #wrapper {
+ width: 700px;
+ margin-left: auto;
+ margin-right: 90px;
+ }
+
+ header {
+ margin: 0;
+ margin-left: -20px;
+ padding: 0;
+ }
+
+ header h1 {
+ margin: 0;
+ margin-top: -8px;
+ padding: 0;
+ font-size: 180px;
+ }
+
+ header a {text-decoration: none; margin: 0}
+
+ a {color: #fff}
+ a:hover {color: #ccc}
+
+ nav {
+ margin-left: -20px;
+ margin-top: 20px;
+ margin-bottom: 10px;
+ font-size: 22px;
+ text-transform: uppercase;
+ font-family: Lucida Grande;
+ }
+
+ nav a {text-decoration: none}
+ nav a:hover {text-decoration: underline}
+
+ ul {padding-left: 5px}
+
+ article#content {
+ line-height: 36px;
+ padding-bottom: 90px;
+ }
+ </style>
+ </head>
+ <body>
+ <div id="wrapper">
+ <nav>
+ <a href="/crashcourse">Crash Course</a> |
+ <a href="/reference">Reference</a> |
+ <a href="https://github.com/mauricemach/zappa/tree/master/examples">Examples</a> |
+ <a href="/zappa.html">Source</a>
+ </nav>
+
+ <header>
+ <h1><a href="/">zappa</a></h1>
+
+ <a href="http://github.com/mauricemach/zappa"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://a248.e.akamai.net/assets.github.com/img/71eeaab9d563c2b3c590319b398dd35683265e85/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67" alt="Fork me on GitHub"></a>
+ </header>
+
+ <article id="content">
+ {{ content }}
+ </article>
+ </div>
+ </body>
+</html>
View
428 docs/crashcourse.md
@@ -0,0 +1,428 @@
+---
+layout: default
+title: Crash Course
+permalink: /crashcourse/index.html
+---
+
+# {{page.title}}
+
+Let's start with the classic:
+
+## Hi, World
+
+Get a `cuppa.coffee`:
+
+{% highlight coffeescript %}
+require('zappa') ->
+ get '/': 'hi'
+{% endhighlight %}
+
+And give your foot a push:
+
+ $ npm install zappa
+ $ coffee cuppa.coffee
+ info - socket.io started
+ Express server listening on port 3000 in development mode
+ Zappa 0.2.0beta orchestrating the show
+
+## Nice, but one-line string responses are mostly useless. Can you show me something closer to a real web app?
+
+{% highlight coffeescript %}
+get '*': '''
+ <!DOCTYPE html>
+ <html>
+ <head><title>Sorry, we'll be back soon!</title></head>
+ <body><h1>Sorry, we'll be back soon!</h1></body>
+ </html>
+'''
+{% endhighlight %}
+
+## Seriously.
+
+Right. This is what a basic route with a handler function looks like:
+
+{% highlight coffeescript %}
+get '/:name': ->
+ "Hi, #{@name}"
+{% endhighlight %}
+
+If you return a string, it will automatically be sent as the response.
+
+Now for a more typical scenario:
+
+{% highlight coffeescript %}
+get '/users/:id': ->
+ User.findById @id, (@err, @user) =>
+ render 'user'
+
+view user: ->
+ if @err
+ @title = 'Error'
+ p "Something terrible happened: #{@err}."
+ else
+ @title = "#{@user.name}'s Home"
+ p "Hullo, #{@user.name}!"
+
+view layout: ->
+ html ->
+ head -> title @title
+ body ->
+ h1 @title
+ @body
+{% endhighlight %}
+
+Handler functions are executed within a specially crafted scope that is optimized for the typical scenario of taking the input, processing it, rendering a view with this data and sending a response, all with *minimal wiring*.
+
+You have certain local variables automatically available such as `request`, `response` and `next` (straight from Express). You also have shortcuts such as `send`, `redirect` and `render`.
+
+Besides being able to read your input through the standard API (ex.: `request.query.foo` and friends), you also have access to a merged collection of them, as `@foo` and the alias `params.foo`.
+
+All variables at `@`/`params` (from input or put there by you) 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:
+
+{% highlight coffeescript %}
+blacklist = ['scope', 'self', 'locals', 'filename',
+ 'debug', 'compiler', 'compileDebug', 'inline']
+app.register '.jade', zappa.adapter 'jade', blacklist
+{% endhighlight %}
+
+To disable it on default zappa:
+
+{% highlight coffeescript %}
+app.register '.coffee', require('coffeekup').adapters.express
+{% endhighlight %}
+
+## Fine. But this is node! What about some async?
+
+Both examples below will produce `bar?!` if you request `/bar`:
+
+{% highlight coffeescript %}
+get '/:foo': ->
+ @foo += '?'
+
+ sleep 3, =>
+ @foo += '!'
+ render 'index'
+{% endhighlight %}
+
+Or if you can't / don't want to use the fat arrow to bind `@`:
+
+{% highlight coffeescript %}
+get '/:foo': ->
+ params.foo += '?'
+
+ sleep 3, ->
+ params.foo += '!'
+ render 'index'
+{% endhighlight %}
+
+## Let me guess. You can also post/put/del, use regexes, routes are matched first to last, all like any self-respecting sinatra clone.
+
+Exactly. Actually, when it comes to HTTP zappa hands over all the serious work to Express, so there are no big surprises here:
+
+{% highlight coffeescript %}
+get '/': 'got'
+post '/': 'posted'
+put '/': 'put'
+del '/': 'deleted'
+get '*': 'any url'
+{% endhighlight %}
+
+## Route combo
+
+The routing functions accept an object where each key is a route path, and each values the response. This means we can define multiple routes in one go:
+
+{% highlight coffeescript %}
+get '/foo': 'bar', '/ping': 'pong', '/zig': 'zag'
+{% endhighlight %}
+
+Better yet:
+
+{% highlight coffeescript %}
+get
+ '/foo': 'bar'
+ '/ping': 'pong'
+ '/zig': 'zag'
+{% endhighlight %}
+
+You can also use the default syntax where the first param is the path, and the second the response. This is mostly to allow for regexes:
+
+{% highlight coffeescript %}
+get '/foo', 'bar'
+get /^\/ws-(.*)/, ->
+ 'bloatware-' + params[0]
+{% endhighlight %}
+
+## Bi-directional events (WebSockets/Comet)
+
+But the web is not just about HTTP requests anymore. WebSockets are soon to become available on all major browsers but IE. For this sucker and legacy browsers, there's a collection of ugly hacks that work (comet), and thanks to Socket.IO, we don't even have to care.
+
+Zappa pushes this trivialization a bit further by removing some of the boilerplate, and providing some integration. The goal is to make event handling feel more like a first-class citizen along with request handling, readily available, instead of an exotic feature you bolt on your app.
+
+All you have to do to handle bi-directional events in your apps is declare the handlers, side by side with your HTTP ones:
+
+{% highlight coffeescript %}
+get '/chat': ->
+ render 'chat'
+
+get '/counter': ->
+ "Total messages so far: #{app.counter}"
+
+at connection: ->
+ app.counter ?= 0
+ emit 'welcome', time: new Date()
+ broadcast "#{id} connected"
+
+at disconnect: ->
+ broadcast "#{id} is gone!"
+
+at said: ->
+ app.counter++
+ broadcast 'said', {id, @text}
+
+at afk: ->
+ broadcast 'afk', {id}
+{% endhighlight %}
+
+When your app starts, if you defined one of those handlers, zappa will automatically require Socket.IO and fire it up. It will not take up a dedicated port, since Socket.IO can attach itself to the HTTP server and intercept WebSockets/comet traffic.
+
+Event and request handlers are designed to behave as similarly as possible. There are locals for the standard API (`io`, `socket`), shortcuts (`emit`, `broadcast`) and input variables are also available at `@`.
+
+## But what about the client-side?
+
+That's an interesting question! Let's start with the basics.
+
+First there's `coffee` with which you can define a route `/file.js`, that will respond with your CoffeeScript code in JS form, and the correct content-type set. No compilation involved, since we already have you function's string representation from the runtime.
+
+{% highlight coffeescript %}
+get '/': -> render 'index'
+
+coffee '/index.js': ->
+ alert 'hullo'
+
+view index: ->
+ h1 'Client embedding example'
+
+view layout: ->
+ html ->
+ head -> title 'bla'
+ script src: '/index.js'
+ body @body
+{% endhighlight %}
+
+On a step further, you have `client`, which gives you access to a matching zappa client-side API:
+
+{% highlight coffeescript %}
+enable 'serve jquery', 'serve sammy'
+
+get '/': ->
+ render 'index', layout: no
+
+at connection: ->
+ emit 'server time', time: new Date()
+
+client '/index.js': ->
+ def sum: (a, b) -> a + b
+
+ get '#/': ->
+ alert 'index'
+
+ at 'server time': ->
+ alert "Server time: #{@time}"
+
+ connect 'http://localhost'
+
+view index: ->
+ doctype 5
+ html ->
+ head ->
+ title 'Client-side zappa'
+ script src: '/socket.io/socket.io.js'
+ script src: '/zappa/jquery.js'
+ script src: '/zappa/sammy.js'
+ script src: '/zappa/zappa.js'
+ script src: '/index.js'
+ body ''
+{% endhighlight %}
+
+Finally, there's also `shared`. Certain zappa "keywords" work exactly the same on the server and client side. Guess what? If you define them inside a `shared` block, they're available at both environments!
+
+{% highlight coffeescript %}
+shared '/index.js': ->
+ def 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
+
+at 'delete everything': ->
+ role 'admin'
+
+client '/index.js': ->
+ get '#/admin': ->
+ role 'admin'
+ # admin stuff
+{% endhighlight %}
+
+## Scope and `def`
+
+In order to gain all these specialized scopes, we lose closures.
+
+To make things available at the root scope:
+
+{% highlight coffeescript %}
+foo = 'bar'
+require('zappa') {foo}, ->
+ console.log foo # 'bar'
+{% endhighlight %}
+
+To make things available to handlers, use `def`:
+
+{% highlight coffeescript %}
+foo = 'bar'
+def ping: 'pong'
+def zig: -> 'zag'
+
+get '/': ->
+ foo # undefined
+ ping # 'pong'
+ zig() # 'zag'
+{% endhighlight %}
+
+## But `def foo: require 'foo'` is stupid repetition! I'm lazy!
+
+Luckily for you, so am I. Meet `requiring`, `require`'s less patient brother.
+
+{% highlight coffeescript %}
+requiring 'fs', 'path', 'util'
+
+get '/': ->
+ console.log fs, path, util
+{% endhighlight %}
+
+## Santa's little `helper`s
+
+Helpers are just like defs, except they are modified to have access to the same context (@/this) and framework locals as whatever called them (request or event handlers).
+
+{% highlight coffeescript %}
+helper role: (name) ->
+ if request?
+ redirect '/login' unless @user.role is name
+ else
+ client.disconnect() unless @user.role is name
+
+get '/gm': ->
+ role 'gm'
+ # see stuff
+
+at kill: ->
+ role 'gm'
+ # kill stuff
+{% endhighlight %}
+
+## Post-rendering with server-side jQuery
+
+Rendering things linearly is often the approach that makes more sense, but sometimes DOM manipulation can avoid loads of repetition. The best DOM libraries in the world are in javascript, and thanks to the work of Elijah Insua with [jsdom](http://jsdom.org/), you can use some with node too.
+
+Zappa makes it trivial to post-process your rendered templates by manipulating them with jQuery:
+
+{% highlight coffeescript %}
+postrender plans: ->
+ $('.staff').remove() if @user.plan isnt 'staff'
+ $('div.' + @user.plan).addClass 'highlighted'
+
+get '/postrender': ->
+ @user = plan: 'staff'
+ render 'index', postrender: 'plans'
+{% endhighlight %}
+
+## App combo
+
+Node.js servers don't block when calling `listen`, so you can run many apps in the same process:
+
+{% highlight coffeescript %}
+zappa = require 'zappa'
+
+zappa 8001, -> get '/': 'blog'
+zappa 8002, -> get '/': 'chat'
+zappa 8003, -> get '/': 'wiki'
+
+$ coffee apps.coffee
+{% endhighlight %}
+
+You can also take advantage of Express/Connect vhost middleware:
+
+{% highlight coffeescript %}
+zappa = require 'zappa'
+
+chat = zappa.app -> get '/': 'chat'
+blog = zappa.app -> get '/': 'blog'
+
+zappa 80, {chat, blog}, ->
+ use express.vhost 'chat.com', chat
+ use express.vhost 'blog.com', blog
+{% endhighlight %}
+
+## Splitting it up
+
+If your single file of doom is becoming unwieldy, you can split it up based on whatever organization suits you better:
+
+{% highlight coffeescript %}
+include 'model'
+include 'controllers/http'
+include 'controllers/websockets'
+include 'controllers/client'
+include 'controllers/common'
+include 'views'
+{% endhighlight %}
+
+Or by subject:
+
+{% highlight coffeescript %}
+include 'users'
+include 'widgets'
+include 'gadgets'
+include 'funzos'
+{% endhighlight %}
+
+The files to be included just have to export an `include` function:
+
+{% highlight coffeescript %}
+# Could be `module.exports.include` as well.
+@include = ->
+ get '/': 'This is a route inside an included file.'
+{% endhighlight %}
+
+## Connect(ing) middleware
+
+You can specify your middleware through the standard `app.use`, or zappa's shortcut `use`. The latter can be used in a number of additional ways:
+
+- It accepts many params in a row. 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')
View
93 docs/css/highlight.css
@@ -0,0 +1,93 @@
+/* Stolen and adapted from https://gist.github.com/803005. */
+
+code {
+ border: 1px solid #444;
+ background: #1c1c1c;
+ color: #c1c1c1;
+ padding: 3px;
+ font-family: Monaco, Consolas, "Lucida Console", monospace;
+ white-space: nowrap;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+ border-radius: 3px;
+}
+
+pre {
+ border: 1px solid #333;
+ background: #181818;
+ padding: 16px;
+ overflow: hidden;
+ width: 100%;
+ overflow: auto;
+ margin: 0;
+ clear: both;
+ line-height: 20px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+ border-radius: 3px;
+}
+
+pre code {
+ border: none;
+ background: none;
+ white-space: pre-wrap;
+}
+
+.highlight .hll { background-color: #ffffcc }
+.highlight .c { color: #5F5A60; font-style: italic } /* Comment */
+.highlight .err { border:#B22518; } /* Error */
+.highlight .k { color: #CDA869 } /* Keyword */
+.highlight .cm { color: #5F5A60; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #5F5A60 } /* Comment.Preproc */
+.highlight .c1 { color: #5F5A60; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #5F5A60; font-style: italic } /* Comment.Special */
+.highlight .gd { background: #420E09 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { background: #B22518 } /* Generic.Error */
+.highlight .gh { color: #000080; } /* Generic.Heading */
+.highlight .gi { background: #253B22 } /* Generic.Inserted */
+.highlight .go { } /* Generic.Output */
+.highlight .gp { } /* Generic.Prompt */
+.highlight .gs { } /* Generic.Strong */
+.highlight .gu { color: #800080; } /* Generic.Subheading */
+.highlight .gt { } /* Generic.Traceback */
+.highlight .kc { } /* Keyword.Constant */
+.highlight .kd { color: #e9df8f; } /* Keyword.Declaration */
+.highlight .kn { } /* Keyword.Namespace */
+.highlight .kp { color: #9B703F } /* Keyword.Pseudo */
+.highlight .kr { } /* Keyword.Reserved */
+.highlight .kt { } /* Keyword.Type */
+.highlight .m { } /* Literal.Number */
+.highlight .s { } /* Literal.String */
+.highlight .na { color: #F9EE98 } /* Name.Attribute */
+.highlight .nb { color: #CDA869 } /* Name.Builtin */
+.highlight .nc { color: #9B859D; } /* Name.Class */
+.highlight .no { color: #9B859D } /* Name.Constant */
+.highlight .nd { color: #7587A6 } /* Name.Decorator */
+.highlight .ni { color: #CF6A4C; } /* Name.Entity */
+.highlight .nf { color: #9B703F; } /* Name.Function */
+.highlight .nn { color: #9B859D; } /* Name.Namespace */
+.highlight .nt { color: #CDA869; } /* Name.Tag */
+.highlight .nv { color: #7587A6 } /* Name.Variable */
+.highlight .ow { color: #AA22FF; } /* Operator.Word */
+.highlight .w { color: #141414 } /* Text.Whitespace */
+.highlight .mf { color: #CF6A4C } /* Literal.Number.Float */
+.highlight .mh { color: #CF6A4C } /* Literal.Number.Hex */
+.highlight .mi { color: #CF6A4C } /* Literal.Number.Integer */
+.highlight .mo { color: #CF6A4C } /* Literal.Number.Oct */
+.highlight .sb { color: #8F9D6A } /* Literal.String.Backtick */
+.highlight .sc { color: #8F9D6A } /* Literal.String.Char */
+.highlight .sd { color: #8F9D6A; font-style: italic; } /* Literal.String.Doc */
+.highlight .s2 { color: #8F9D6A } /* Literal.String.Double */
+.highlight .se { color: #F9EE98;; } /* Literal.String.Escape */
+.highlight .sh { color: #8F9D6A } /* Literal.String.Heredoc */
+.highlight .si { color: #DAEFA3;; } /* Literal.String.Interpol */
+.highlight .sx { color: #8F9D6A } /* Literal.String.Other */
+.highlight .sr { color: #E9C062 } /* Literal.String.Regex */
+.highlight .s1 { color: #8F9D6A } /* Literal.String.Single */
+.highlight .ss { color: #CF6A4C } /* Literal.String.Symbol */
+.highlight .bp { color: #00aaaa } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #7587A6 } /* Name.Variable.Class */
+.highlight .vg { color: #7587A6 } /* Name.Variable.Global */
+.highlight .vi { color: #7587A6 } /* Name.Variable.Instance */
+.highlight .il { color: #009999 } /* Literal.Number.Integer.Long */
View
BIN  docs/favicon.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  docs/images/zappa.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
86 docs/index.md
@@ -0,0 +1,86 @@
+---
+layout: default
+title: Radically focused, CoffeeScript-oriented interface for building web apps on Node.js with Express and Socket.IO.
+---
+
+# Node development for the lazy
+
+Zappa is a radically focused, [CoffeeScript](http://coffeescript.org)-oriented interface for building web apps on [Node.js](http://nodejs.org) with [Express](http://expressjs.com) and [Socket.IO](http://socket.io).
+
+It turns this:
+
+{% highlight coffeescript %}
+app = require('express').createServer()
+io = require('socket.io').listen(app)
+
+app.use express.bodyParser()
+app.use express.methodOverride()
+app.use app.router
+app.use express.static __dirname + '/public'
+
+app.configure 'development', ->
+ app.use express.errorHandler dumpExceptions: on
+
+app.configure 'production', ->
+ app.use express.errorHandler()
+
+app.get '/:foo', (req, res) ->
+ req.params.foo += 'bar'
+ res.render 'index', foo: req.params.foo
+
+io.sockets.on 'connection', (socket) ->
+ socket.emit 'welcome', time: new Date()
+
+ socket.on 'shout', (data) ->
+ socket.broadcast.emit 'shout',
+ id: socket.id, text: data.text
+
+app.listen 3000
+{% endhighlight %}
+
+Into this:
+
+{% highlight coffeescript %}
+require('zappa') ->
+ use 'bodyParser', 'methodOverride', app.router, 'static'
+
+ configure
+ development: -> use errorHandler: {dumpExceptions: on}
+ production: -> use 'errorHandler'
+
+ get '/:foo': ->
+ @foo += 'bar'
+ render 'index'
+
+ at connection: ->
+ emit 'welcome', time: new Date()
+
+ at shout: ->
+ broadcast 'shout', {id, @text}
+{% endhighlight %}
+
+## Learn More
+
+- Get the gist with the [crash course](/crashcourse)
+
+- Check the [API reference](/reference)
+
+- See the [examples](https://github.com/mauricemach/zappa/tree/master/examples) included with the source
+
+- Read the [annotated source](/zappa.html) generated by [docco](http://jashkenas.github.com/docco/)
+
+## Other resources
+
+- The source code [repository](http://github.com/mauricemach/zappa) at github
+
+- Questions, suggestions? Drop us a line on the [mailing list](http://groups.google.com/group/zappajs)
+
+- Rather do it realtime? Join the IRC channel on freenode: [#zappajs]((irc://irc.freenode.net/zappajs)
+
+- Found a bug? Open an [issue](http://github.com/mauricemach/zappa/issues) at github
+
+- Check the project's history at the [change log](https://github.com/mauricemach/zappa/blob/master/CHANGELOG.md)
+
+- Migrating from 0.1.x? See what changed in [v0.2.x](/peaches), and follow the [quick guide](/migration)
+
+- Deploying to heroku? Check [this blog post](http://blog.superbigtree.com/blog/2011/08/19/hosting-zappa-0-2-x-on-heroku/)
View
10 docs/migration.md
@@ -1,8 +1,10 @@
-# Migration to zappa 0.2.x
+---
+layout: default
+title: 'Migration from 0.1.x: TL;DR guide'
+permalink: /migration/index.html
+---
-## TLDR; guide
-
-**This may not be an exhaustive list. Contributions are welcome.**
+# {{page.title}}
Commands
View
230 docs/peaches.md
@@ -1,4 +1,10 @@
-# Zappa 0.2.x "Peaches en Regalia"
+---
+layout: default
+title: v0.2.x "Peaches en Regalia"
+permalink: /peaches/index.html
+---
+
+# {{page.title}}
Zappa was conceived almost a year ago as a crazy experimentalist hack to explore possibilities in the then forming and rapidly changing Node.js/CoffeeScript "platform". Since then this "platform" matured a great deal, and it's high time zappa is consolidated into something really usable, and more in tune with today's node development ecosystem.
@@ -110,131 +116,139 @@ All work and no play makes zappa a dull module! Even though Peaches is mainly ab
If you use `shared '/foo.js' ->` instead, the block of code will be both evaluated on the server and served to the client. Ex.:
- shared '/shared.js': ->
- def sum: (a, b) ->
- a + b
-
- if window
- alert 'Running on the browser!'
- else
- console.log 'Running on the server!'
+{% highlight coffeescript %}
+shared '/shared.js': ->
+ def sum: (a, b) ->
+ a + b
- client '/index.js': ->
- get '#/': -> console.log sum 5, 8
+ if window
+ alert 'Running on the browser!'
+ else
+ console.log 'Running on the server!'
- get '/': -> console.log sum 3, 6
+client '/index.js': ->
+ get '#/': -> console.log sum 5, 8
+
+get '/': -> console.log sum 3, 6
+{% endhighlight %}
## Nice, now please show me some freaking code!
With all this standardization talk you'd expect zappa apps to now look a lot different from they did in Jazz. But in practice, the basic structure remains the same:
- require('zappa') ->
- include 'sub'
-
- def foo: 'bar'
-
- helper role: (name) ->
- redirect '/' unless @user.role is name
-
- get: '/': 'hi'
-
- get: '/': ->
- @foo = 'bar'
- render 'index'
-
- coffee '/index.js': ->
- alert 'hi'
- # socket.io code here.
-
- at connection: ->
- broadcast "#{@id} connected"
-
- at hello: ->
- emit 'reply', foo: 'bar'
-
- view index: ->
- h1 @foo
-
- view layout: ->
- doctype 5
- html ->
- head ->
- title 'Foo'
- script src: '/socket.io/socket.io.js'
- script src: '/index.js'
- link rel: 'stylesheet', href: '/index.css'
- body @body
-
- css '/index.css': '''
- font-family: sans-serif;
- '''
+{% highlight coffeescript %}
+require('zappa') ->
+ include 'sub'
+
+ def foo: 'bar'
+
+ helper role: (name) ->
+ redirect '/' unless @user.role is name
+
+ get: '/': 'hi'
+
+ get: '/': ->
+ @foo = 'bar'
+ render 'index'
+
+ coffee '/index.js': ->
+ alert 'hi'
+ # socket.io code here.
+
+ at connection: ->
+ broadcast "#{@id} connected"
+
+ at hello: ->
+ emit 'reply', foo: 'bar'
+
+ view index: ->
+ h1 @foo
+
+ view layout: ->
+ doctype 5
+ html ->
+ head ->
+ title 'Foo'
+ script src: '/socket.io/socket.io.js'
+ script src: '/index.js'
+ link rel: 'stylesheet', href: '/index.css'
+ body @body
+
+ css '/index.css': '''
+ font-family: sans-serif;
+ '''
+{% endhighlight %}
At sub.coffee:
-
- # Could also be `module.exports.include`.
- @include = ->
- get '/sub': -> render 'sub'
- view sub: ->
- p 'Sub module included'
+{% highlight coffeescript %}
+# Could also be `module.exports.include`.
+@include = ->
+ get '/sub': -> render 'sub'
+
+ view sub: ->
+ p 'Sub module included'
+{% endhighlight %}
The actual big difference is what you **can** do now:
-
- zappa = require 'zappa'
- chat = zappa.app ->
- set 'view engine': 'jade'
- app.register '.jade', zappa.adapter 'jade'
-
- io.set 'log level', 1
+{% highlight coffeescript %}
+zappa = require 'zappa'
+
+chat = zappa.app ->
+ set 'view engine': 'jade'
+ app.register '.jade', zappa.adapter 'jade'
+
+ io.set 'log level', 1
- enable 'serve jquery'
-
- use 'cookieParser', 'bodyParser'
+ enable 'serve jquery'
+
+ use 'cookieParser', 'bodyParser'
- configure development: ->
- use errorHandler: {dumpExceptions: yes}
+ configure development: ->
+ use errorHandler: {dumpExceptions: yes}
- shared '/shared.js': ->
- def sum: (a, b) -> a + b
+ shared '/shared.js': ->
+ def sum: (a, b) -> a + b
- get '/': ->
- @foo = 'bar'
- render 'index'
-
- at connection: ->
- broadcast 'joined', {id}
+ get '/': ->
+ @foo = 'bar'
+ render 'index'
+
+ at connection: ->
+ broadcast 'joined', {id}
- client '/index.js': ->
- connect()
-
- at joined: ->
- alert "#{@id} joined us."
-
- view index: '''
- h1= foo
- '''
-
- view layout: '''
- !!! 5
- html
- head
- title A Jade template!
- script(src='/socket.io/socket.io.js')
- script(src='/zappa/jquery.js')
- script(src='/zappa/zappa.js')
- script(src='/shared.js')
- script(src='/index.js')
- body!= body
- '''
-
- wiki = zappa.app ->
- get '/': 'wiki'
- # wiki code here...
-
- zappa 80, {chat, wiki}, ->
- use express.vhost 'chat.com', chat.app
- use express.vhost 'wiki.com', wiki.app
+ client '/index.js': ->
+ connect()
+
+ at joined: ->
+ alert "#{@id} joined us."
+
+ view index: '''
+ h1= foo
+ '''
+
+ view layout: '''
+ !!! 5
+ html
+ head
+ title A Jade template!
+ script(src='/socket.io/socket.io.js')
+ script(src='/zappa/jquery.js')
+ script(src='/zappa/zappa.js')
+ script(src='/shared.js')
+ script(src='/index.js')
+ body!= body
+ '''
+
+wiki = zappa.app ->
+ get '/': 'wiki'
+ # wiki code here...
+
+zappa 80, {chat, wiki}, ->
+ use express.vhost 'chat.com', chat.app
+ use express.vhost 'wiki.com', wiki.app
+{% endhighlight %}
## What's next?
View
50 docs/reference.md
@@ -1,18 +1,22 @@
-# Zappa 0.2.0beta2 reference
+---
+layout: default
+title: API Reference (v0.2.0beta2)
+permalink: /reference/index.html
+---
-**This reference is a work in progress. There are still many sections to be added or refined.**
+# {{page.title}}
-**Please note that the API is subject to change while in beta.**
+**Please note this is a work in progress. There are still many sections to be added or refined.**
-## Zappa function
+## EXPORTS
-`require 'zappa'` returns a function equivalent to `zappa.run`. It also has the following attributes:
+`require 'zappa'` returns a function with the following attributes:
-### zappa.version
+### version
Version of zappa running.
-### zappa.app
+### app
`zappa.app [locals,] function`
@@ -32,19 +36,29 @@ It will also lose access to its parent scope in the process, so any variables fr
Returns an object with attributes `id` (uuid generated for this app), `app` (express server) and `io` (socket.io server).
-### zappa.run
+### 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, object is locals 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).
-## zappa.adapter
+### adapter
Creates a zappa view adapter to be used with `app.register`. See `view`.
-## Root scope
+## ROOT SCOPE
+
+The function you pass to `zappa.app` or `zappa.run` will be modified to include these variables:
### @/this
@@ -351,13 +365,13 @@ Shortcut to `app.disable`. Accepts multiple params in one go. Ex.:
disable 'serve jquery', 'serve sammy'
-### global, process, console, setTimeout, clearTimeout, setInterval, clearInterval, require, __filename, __dirname, module
+### global, process, console, setTimeout, clearTimeout, setInterval, clearInterval, require, \__filename, \__dirname, module
Node.js's global variables.
`require`, `module`, `__filename` and `__dirname` are not actually globals, but local to each module.
-## Request handlers scope
+## REQUEST HANDLERS SCOPE
### @
@@ -397,7 +411,7 @@ Two additional features:
Shortcut to `response.redirect`.
-## Sockets handlers scope
+## SOCKETS HANDLERS SCOPE
### @
@@ -427,9 +441,9 @@ Shortcut to `socket.emit`.
Shortcut to `socket.broadcast`.
-## View scope
+## VIEW SCOPE
-## Client-side root scope
+## CLIENT-SIDE ROOT SCOPE
### get, post, put, del
@@ -447,11 +461,11 @@ Same as its server-side counterpart.
Same as its server-side counterpart.
-## Client-side route scope
+## CLIENT-SIDE ROUTE HANDLERS SCOPE
-## Client-side socket scope
+## CLIENT-SIDE SOCKETS HANDLERS SCOPE
-## App settings
+## APP SETTINGS
You can use the following options with `set`, `enable` and `disable`:
Please sign in to comment.
Something went wrong with that request. Please try again.