Aura 1.0pre

Aura is a decoupled, event-driven architecture for developing widget-based applications. It takes advantage of patterns and best practices for developing maintainable applications and gives you greater control over widget-based development. Aura gives you complete control of a widget's lifecycle, allowing developers to dynamically start, stop, reload and clean-up parts of their application as needed.

Concepts

The `Aura` object

Your application will be an instance of the Aura object.

Its responsibilities are to load extensions when the app starts and clean them up when the app stops.

Extension

Extensions are loaded in your application when it starts. They allow you to add features to the application, and are available to the widgets through their sandbox.

Core

The core implements aliases for DOM manipulation, templating and other lower-level utilities that pipe back to a library of choice. Aliases allow switching libraries with minimum impact on your application.

Sandbox

A sandbox is just way to implement the facade pattern on top of features provided by core. It lets you expose the parts of a JavaScript library that are safe to use instead of exposing the entire API. This is particularly useful when working in teams.

When your app starts, it will create an instance of sandbox in each of your widgets.

Widget

A widget represents an unit of a page. Each widget is independent. This means that they know nothing about each other. To make them communicate, a Publish/Subscribe (Mediator) pattern is used.

Getting started

Requirements

bower: run npm install -g bower if needed

Building Aura.js

Run npm install to install Aura dependencies. Bower dependencies will be automatically installed.
Run grunt build. aura.js will be placed in dist/.

How to run tests

Browser

Run grunt. Then visit http://localhost:8899/spec/.

CLI

Run npm test.

Creating an Application

The first step in creating an Aura application is to make an instance of Aura.

var app = new Aura();

Now that we have our app, we can start it.

app.start({
  widget: 'body'
});

This starts the app by saying that it should search for widgets anywhere in the body of your HTML document.

Creating a Widget

By default widgets are retrieved from a directory called widgets/ that must be at the same level as your HTML document.

Let's say we want to create an "hello" widget. To do that we need to create a widgets/hello/ directory

This directory must contain:

A main.js file. It will bootstrap and describe the widget. It is mandatory, no matter how small it can be.
All the other files that your widget needs (models, templates, …).

For our "hello" widget the main.js will be:

define({
  initialize: function () {
    this.$el.html('<h1>Hello Aura</h1>');
  }
});

Declaring a Widget

Add the following code to your HTML document.

<div data-aura-widget="hello"></div>

Aura will call the initialize method that we have defined in widgets/hello/main.js.

Creating extension

Imagine that we need an helper to reverse a string. In order to accomplish that we'll need to create an extension.

define('extensions/reverse', {
  initialize: function (app) {
    app.core.util.reverse = function (string) {
      return string.split('').reverse().join('');
    };
  }
});

Using extension

To make our reserve helper available in our app, run the following code:

app.use('extensions/reverse');

This will call the initialize function of our reserve extension.

Calling use when your app is already started will throw an error.

Project status

Aura 0.9.x was well received by the developer community, but had regular requests for a few advanced capabilities. These included individual sandboxes, declarative widgets, support for Bower and a powerful Pub/Sub implementation amongst others.

To cater for this, Aura has been getting a heavy re-write over the past few months and we anticipate releasing a beta that can be tested in April, 2013. This will be followed by detailed documentation and new demo applications.

A version of Aura currently powers the Hull.io widget platform and we are honored to have members of that team directly contributing to the next version of the project.

johnnychq/aura