From 7d54aff86434f45412f36c38ce0e14886175c84a Mon Sep 17 00:00:00 2001 From: dsc Date: Thu, 19 Jul 2012 10:31:56 -0700 Subject: [PATCH] Initial commit. --- Contributing.md | 57 ++++++++++++++++++++++++++++++++++++++++++ Getting-Started.md | 28 ++++++++++++++++++++ Middleware.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 0 deletions(-) create mode 100644 API-Reference.md create mode 100644 Client-Only.md create mode 100644 Contributing.md create mode 100644 DataSource-Meta.md create mode 100644 Feature-Walkthrough.md create mode 100644 Getting-Started.md create mode 100644 Home.md create mode 100644 Internals.md create mode 100644 Middleware.md create mode 100644 Roadmap.md create mode 100644 Vision.md diff --git a/API-Reference.md b/API-Reference.md new file mode 100644 index 0000000..e69de29 diff --git a/Client-Only.md b/Client-Only.md new file mode 100644 index 0000000..e69de29 diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..cf54b03 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,57 @@ +## Development Installation + +This is a [node.js][nodejs] project, so you need node >0.8.x and the node package manager, [npm][npm]. + +Once that's done, I recommend you install Coco globally so you don't have to futz with your path: `npm install -g coco` -- if you choose not to, you should probably add `./node_modules/.bin` to `PATH` in your bashrc or something. + +Next, install your source checkout in dev mode by running `npm link` from the project root. This will also download and install all the package dependencies. + +Finally, start the `server` task using Coke (it's like Rake for Coco) with `coke server`. While this does what it says on the tin, it also seems to have a habit of randomly losing parts of stderr. For now, you can work around this by manually starting the server: `coke link && lib/server/server.co` + +You should now have a server running on 8081. + +### Project Layout +- assets/ - static images +- data/ - json, yaml, csv, etc. files that contain graph configuration and graph content data +- data/datasources/ - graph content data +- data/graphs/ - saved graph configurations. +- lib/ - [Coco][coco] files. Application logic lives here. +- lib/{chart,dashboard,dataset,graph}/ - Models and View Classes +- lib/template/ - client side [Jade][jade] views. These are included and rendered by View classes. +- lib/server/ - Server side [Coco][coco] files. +- lib/server/server.co - [Express][expressjs] server setup. Routing is done here. +- lib/server/controllers/ - Server side controllers. Routed to by [express-resource][]. +- www/ - (Mostly) static [Jade][jade] HTML templates and [Stylus][stylus] CSS templates. The [Jade][jade] templates are rendered by the server side controllers in lib/server/controllers/. +- var/ - Compiled JavaScript and CSS files. + +## Deployment +Coco needs to be compiled down to JavaScript in order for it to be executed. In development environments, this is done on the fly. In production environments, all Coco is compiled down into JavaScript files and placed in a dist/ directory. These JavaScript (and compiled Stylus CSS files) are served up directly to the browser upon request, rather than having to be compiled first. + +deploy.sh currently builds a distribution tmp/dist, and then rsyncs this over to reportcard.wmflabs.org. You will need an account with sudo permissions on reportcard2.pmtpa.wmflabs in order to deploy. + + +## Notes + +- This project is written in [Coco][coco], a dialect of [CoffeeScript][coffee] -- they both compile + down to JavaScript. The pair are very, very similar, [except][coco-improvements] + for [a few][coco-incompatibilities] [things][coco-vs-coffee]. If you can read JavaScript and Ruby, + you can understand Coco and CoffeeScript. (I refer to the [CoffeeScript docs][coffee-docs] for + the syntax, and I find the [comparison page][coco-vs-coffee] to be the best reference for Coco.) + +- Coco require compilation before it'll run in the browser (though node can run it directly -- `#!/usr/bin/env coco` will work as a shebang as well). I've written [request middleware][connect-compiler] that recompiles stale files on demand, and it is pretty cool. + + + +[nodejs]: http://nodejs.org/ +[npm]: http://npmjs.org/ +[coco]: https://github.com/satyr/coco +[coco-vs-coffee]: https://github.com/satyr/coco/wiki/side-by-side-comparison +[coco-improvements]: https://github.com/satyr/coco/wiki/improvements +[coco-incompatibilities]: https://github.com/satyr/coco/wiki/incompatibilities +[coffee]: http://coffeescript.org/ +[coffee-docs]: http://coffeescript.org/#language +[connect-compiler]: https://github.com/dsc/connect-compiler +[jade]: https://github.com/visionmedia/jade +[expressjs]: http://expressjs.com/guide.html +[express-resource]: https://github.com/visionmedia/express-resource +[stylus]: http://learnboost.github.com/stylus/ diff --git a/DataSource-Meta.md b/DataSource-Meta.md new file mode 100644 index 0000000..e69de29 diff --git a/Feature-Walkthrough.md b/Feature-Walkthrough.md new file mode 100644 index 0000000..e69de29 diff --git a/Getting-Started.md b/Getting-Started.md new file mode 100644 index 0000000..a1b0755 --- /dev/null +++ b/Getting-Started.md @@ -0,0 +1,28 @@ +If you already have an excellent [Connect][connect]/[Express][express] application, using Limn is very simple. + +1. Install the package via [npm][npm]: + +```sh +cd path/to/your/project +npm install limn +``` + +2. Add Limn as middleware: + +```js +var limn = require('limn'); + +app = express.createServer(); + +// ... other configuration ... + +// mount Limn at /vis +app.use('/vis', limn({ + dataDir : './data' +})); +``` + +See the [Middleware wiki page][limn_middleware] for more info. + +3. Finally, you'll next need to configure Limn to know about your datasources (though in the future we aim for the client to be able introspect this information from the data). + diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..e69de29 diff --git a/Internals.md b/Internals.md new file mode 100644 index 0000000..e69de29 diff --git a/Middleware.md b/Middleware.md new file mode 100644 index 0000000..520547a --- /dev/null +++ b/Middleware.md @@ -0,0 +1,65 @@ +Limn is an [Express][express] application, allowing it to be effortlessly composed as middleware with both Express and [Connect][connect] applications. + + +You mount Limn in your application the same as you would other piece of middleware, by passing it to `app.use()`. + +Via [Express][express]: + +```js +var limn = require('limn') +, express = require('express') +; + +var app = express.createServer() + .use( express.logger('dev') ) + .use( express.static('public') ) + +app.get( '/', function(req, res){ + res.send('hello world'); +}) + + // Mount Limn at /vis +app.use( '/vis', limn({ + varDir : './var', + dataDir : './data', + proxy : true + }) ); + +app.listen(3000); +``` + + +Or via plain [Connect][connect]: + +```js +var limn = require('limn') +, connect = require('connect') +; + +var app = connect.createServer() + .use( connect.logger('dev') ) + .use( connect.static('public') ) + + // Mount Limn at / + .use( limn({ + varDir : './var', + dataDir : './data', + proxy : true + }) ); + +app.listen(3000); +``` + + +## Options + +- `dataDir` -- [$CWD/data] Path to directory where data files should be written. +- `proxy` + - `enabled` -- [false] Enables remote dataset proxy. If omitted, the proxy will be enabled if either `proxy.whitelist` or `proxy.blacklist` are set. + - `whitelist` -- Array of domain patterns to whitelist for proxy. Strings are matched via glob-like syntax, but regular expressions may also be passed. If `proxy.enabled` is true but no whitelist is provided, it defaults to `['*']`. + - `blacklist` -- Array of domain patterns to blacklist from proxying. Strings are matched via glob-like syntax, but regular expressions may also be passed. + + + +[express]: http://expressjs.com "Express" +[connect]: http://senchalabs.org/connect "Connect" diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..e69de29 diff --git a/Vision.md b/Vision.md new file mode 100644 index 0000000..e69de29 -- 1.7.0.4