ash

Ash welcomes you

Ash is a distributed presentation framework for the bohemian web developer. Executed on Node.js or run in the client, Ash provides an intuitive, unrestrictive boudoir in which creators can frolic with and fondly tease the interwebs. The truths and understandings upheld in the body of code known as Ash are;

• Distributed MVC that executes on both client & server
• Code, Convention, Configuration

I'm still smoking this one

The project is still in its early stages and is currently showing signs of emergent behavior. Once it chills out I'll add the obligatory "Getting Started" documentation here.

The Story So Far

Ash helps you develop HTML5 applications that run 100% in web browsers or in containers like PhoneGap. With a bit of extra thinking you can serve these same applications as traditional web sites to maximize your codes use.

Run as a Web Server

Install Ash;

npm install ash -g

Create a file called helloworld.js in an empty directory;

define({
    index: function (api) {
        api.done("Hello world.");
    }
});

In the same directory start Ash;

ash start

Open http://localhost:3000/?module=helloworld&method=index in a browser.

Run as a HTML5 Application

To run the same code 100% in the browser you need to add a file named init.js with the content;

require(["lib/adapters/dom"]);

Then start Ash in webapp mode;

ash webapp

Open http://localhost:3000/?module=helloworld&method=index in a browser.

The Idea

A Serializable Request Object

request = {
    module: "", // a relative path to a module
    method: "", // the function to call on the module
    inputs: {} // a map of values to be made avaliable to the function 
};

A Functional Response Object

response = {
    done: function (data, meta){
        // Adapter to runtime
    },
    flush: function (data, meta) {
        // Adapter to runtime
    }
};

A Single Dispatcher Function

dispatcher = function (request, response) {
    // Map request object to function (api)
};

A Runtime Agnostic Api Object

api = {
    done: response.done,
    flush: response.flush,
    dispatch: dispatcher,
    use: { /* helpers */ }
};

Function Collections

Defined using the Asynchronous Module Definition API, Function Collections are a grouping mechanism for organizing your code. Each function defined in the collection must take exactly one argument, the value of which is a Runtime Agnostic Api Object.

define({
    index: function (api) {
        api.done("Hello world.");
    }
});

Helper Objects

Defined using the Asynchronous Module Definition API, helpers are attached to a Runtime Agnostic Api Object when specified in Function Collections. Helpers can implement the function init(), which if present will be called immediately after the helper is created.

define({
	init: function (request, response, api) {
		// Store for use later
	},
	func: function () {
		// Add functions
	}
});

Helpers are specified in Function Collections by the use of a helpers attribute whose value is an array.

define({
	helpers: ["config"],
    index: function (api) {
		var module = api.use.config.get("module");
        api.done("This is module: " + module);
    }
});

The API

A Module

The modules name it's relative path to the applications root (normally where you start Ash). For example the file ./foo.js would have a module name of foo and the file ./foo/bar/baz.js would be named foo/bar/baz.

define({
    bar: function (api) {
        api.done("Hello world.");
    },
	baz: function (api) {
		api.done("Goodbye cruel world.");
	}
});

Default URI Mapping to Module

http://localhost:3000/?module=foo&method=baz

this.helpers

define({
    helpers: ["a", "b", "c"],
	bar: function (api) {
		var baz = api.use.a.func();
		api.done(baz);
	}
});

The Api Object

api.done

api.done(data, meta);

api.flush

api.flush(data, meta);

api.dispatch

api.dispatch(request, response);

api.use

api.use.module_name.module_func();

A Helper Module

define({
	bar: function (baz) {
		return baz + 1;
	}
});

this.init

define({
	init: function (request, response, api) {
		// ...
	},
	bar: function (baz) {
		return baz + 1;
	}
});

-- http://progmofo.com/