Overview

Thanks for checking out redoak! The aim of this project is to allow rapid prototyping of HTML without getting in the way of your usual workflow. There are no manifestos or revolutions, just faster development.

This tool provides for everyone:

A server that serves up your HTML, and refreshes the page when the HTML or any of its dependencies change.
Ability to make reusable components that are lightweight and easy to write.
A mixin system that allows components to take on multiple features.

For developers:

A tiny client side API for constructing and customizing components.
A flexible and tiny event system.
A straightforward way to split up components and test them with mock data.

Anti-goals:

This project will never be a comprehensive toolkit. You are encouraged to use jQuery, backbone, underscore.js, whatever with redoak! It should be possible to use this with non-node projects: django, tornado, rails, and so forth.
No database model middleware.
Live updating of client code on your development server. The websocket connection is for development purposes only.

This project is brand new and is still evolving rapidly. Please give it a try and file lots of bugs! Patches are appreciated as well.

Diving in

You will need node and npm to get started. If you are new to node, after you download redoak, you will need to run in the redoak directory:

npm install

The best way to get the gist of it is to try it. After you install redoak, just run:

bin/redoak public/todo.html

Navigate to http://localhost:3000/, fire up your favorite editor and start playing. :) You can add files to public/, and they should be visible to the webserver.

Scripting and redoak

You don't need to know Javascript in order to use redoak. You can use it to write HTML and CSS, and it provides you a way to do it without copy and pasting your HTML for components such as complex list items.

It's also possible to use redoak for developing serious web applications (please see the section below), and should play nice with all sorts of technologies, both client side and server side. Read on to learn about its client-side API.

Widget

As you'll see in todo.html, Widgets are responsible for managing the html inside template tags once it is injected into the DOM. HTML injected server side has auto-generated javascript constructs these widgets. HTML created on the client side can be done like so:

var widget = new Widget(['mytemplatename']);
widget.render(document.body, null, { data: 'data for template' });

Widgets are hierarchical and may contain other Widgets, so that you can easily create and dispose groups of widgets with a single call.

Methods of Widget

See lib/public/widget.js for now.

Lifecycle of Widget

Construction. At this point, it has no children and has no HTML it is responsible for.
Rendering. After this, the widget is expected to be responsible for a DOM subtree. It should be able to modify it, to destroy it, and to add to it. It's probably a bad idea to have other objects change this subtree without the widget knowing about it (unless, the other object is a child widget).
Disposal. The widget removes the subtree and cleans up after itself. After disposal, widget should not be reused.

Events

Events in redoak serve two purposes. They serve the typical purpose of learning something about a widget when its state changes, but events are also a way of implementing methods on widgets. redoak's server code uses events to implement template rendering and listening for events.

The standard events of a widget

init(mixins): Widget has just been constructed.
addChild(childWidget): child has been added. May happen before or happen widget has been rendered.
html(): Called when render() is called to get the HTML for this type of widget. Normally implemented by autogenerated JS from redoak. Whoever implements html() should also implement els().
els(): Called right after widget has HTML attached, and before rendered. This gives the dictionary object used for widget.el(), and is normally implemented by autogenerated JS.
rendered(obj): widget just rendered with this object as the template parameters. Widget was either rendered using assign() where the HTML already existed or render() where HTML was generated.
fill(obj): Call this to change the HTML to reflect a new object. Normally implemented by autogenerated JS.
dispose(): widget is being destroyed. All of its children have already been destroyed by this event.

Understanding the code

Server side code

Check out lib/dependencies.js. It's responsible for parsing the HTML, picking out any CSS links or script tags, and watching them all for any changes. The other important file is lib/render.js. It processes the tree, and generates widget code and the final HTML.

Client side code

All in lib/public/. The important file is really widget.js, which contains the Widget prototype.

lib/public/util.js contains the code for events.

Testing

For all tests, if no output is generated after you run the node script, congratulations, it passed!

To run all the tests:

node test.js

Unit tests

Some of the library files have unit tests. You can just run the file to see if they pass. For example:

node lib/fileobj.js

Reftests

Reftests check output of oak files (*.oak.html) with expected HTML output (*.html). To run:

node reftest/reftest.js

It diffs the output of a sample oak file with the expected HTML.

Gentests

Finally, there's now some basic sanity tests for the automatically generated Javascript. To run:

node gentest/gentest.js

Using it in your web app

Unless you want to contribute, I wouldn't recommend using it in anything serious yet. Little thought has been given to browser compatibility or how to incorporate it into a larger scope project. Optimization should be pretty straightforward, but that work hasn't been done yet.

If that didn't scare you, here's how I'm doing it so far: I just require redoak and use the express middleware with some static handlers for dependencies. For session-specific data or DB model data, I've been including a separate JS file so that everything else can stay static and cached. If you write a tag whose src starts with a / like:

<script src='/session.js'></script>

Then redoak will ignore it. There should probably be a way to render widgets from your DB on the server, eventually.

If you use node, see bin/redoak for how to use it in your module. If you don't, there's some work that still needs to be done. :)

Contributors to redoak

Emma Zhou: typo in README.
Itai Zuckerman: todo example delete functionality. Bugfix for preserve mixin and disposing widgets. Bugfix for event listeners.

stechz/redoak