halo-mvc
v1.3.1Halo
Client-side MVC framework based on Addy Osmani's Aura.
Getting Started
Download the production version or the development version.
In your web page:
<script src="dist/Halo.js"></script>
<script>
// Define a controller. Each controller has its start/stop methods proxied via Sauron, a global mediator.
define('controllers/main', ['jquery', 'mvc!c/HtmlController'], function ($, HtmlController) {
var params = {
// Name of the controller -- this acts as the channel for Sauron
'name': 'main',
// Start method to call -- invoked via Sauron.controller('main').start(args);
'start': function (data, cb) {
// Generate and callback with some content $("<div>hello world</div>")
var $content = $('<div>' + data + '</div>');
cb($content);
}
};
return HtmlController(params);
});
// Require Sauron and our controller
require(['Sauron', 'controllers/main'], function (Sauron) {
// Start the controller and render $content to $main
var $main = $('body');
// These are the (data, cb) passed to the 'start' defined above via Sauron, our global mediator.
// The first parameter is stripped and used as the container for the called-back $content
Sauron.controller('main').start($main, 'hello world', function () {
// The callback is wrapped such that $content is automatically appended to $main
$main.html(); // "<div>hello world</div>"
});
});
</script>
There are also a bunch of framework-specific libraries to make your life easier. Continue reading Documentation to find our more.
Documentation
Halo comes packaged with require.js and jquery as well as a bunch of MVC nicities.
Each script is namespaced within require.js to its own filename (except for require.js).
External libraries
File | Require.js namespace | Description |
---|---|---|
require.js | N/A | AMD loader which exposes require and define globally. |
jquery.js | jquery |
One does not simply describe jQuery. |
socket.io | socket.io |
Cross-browser WebSocket implementation. |
Sauron | Sauron |
Mediator which provides a channel system for talking between models and controllers. |
Builder | Builder |
Build chain for client-side MVC views. You will <3 me later. |
Framework-specific libraries
mvc
mvc
is a require.js plugin which allows for easy routing to your models, views, and controllers. For example,
require(['mvc!m/user']); // is equivalent to require(['models/user.js']);
require(['mvc!v/main']); // is equivalent to require(['text!views/main.html']);
require(['mvc!c/home']); // is equivalent to require(['controllers/home.js']);
// Coming soon!
require(['mvc!c/main!c/home!m/user']); // is equivalent to...
// require(['controllers/main.js', 'controllers/home.js', 'models/user']);
mvc
is configured via require.js' configuration.
require.config({
'paths': {
_modelDir: 'path/to/models', // Default: 'models'
_modelExt: '.modelExtension', // Default: '.js'
_controllerDir: 'path/to/controllers', // Default: 'controllers'
_controllerExt: '.controllerExtension', // Default: '.js'
_viewDir: 'path/to/views', // Default: 'views'
_viewExt: '.viewExtension', // Default: '.html'
}
});
URLs are constructed via directory + '/' + module + extension
.
Models
Halo comes with two model templates for usage: CrudModel
and SocketModel
.
CrudModel
provides the memory
mixin and Sauron hooks for create
, retrieve
, update
, and delete
.
SocketModel
extends on top CrudModel
by adding a socket.io to all methods, this.socket
,
as well as Sauron hooks for createEvent
, updateEvent
, and deleteEvent
which are intended to handle server push events.
More information on CrudModel
, SocketModel
, and their mixins/methods can be found in [docs/models.md][docModels].
Controllers
There are two controller templates available: BaseController
and HtmlController
.
BaseController
does not provide any mixins by default and binds start
and stop
to Sauron listeners.
HtmlController
wraps BaseController
and proxies start
and stop
to append and remove generated content respectively.
Detailed explanations of BaseController
, HtmlController
, and their behaviors can be found in docs/controllers.md.
Views
We have tried to stay as true to the thought
A view is markup and interactive logic
as much as possible.
As a result, we built tools like Builder and jqueryp to make all of your interactive set up a breeze.
Further documentation can be can be found in docs/views.md
Examples
Full stack
// index.html
<script>
// Configure everything and kick-off the index controller
require(['config'], function () {
require(['Sauron', 'mvc!c/index'], function () {
Sauron.controller('index').start(document.body, function () {
// document.body will either display an error message about failing to load user
// or it will display the user's name and email
});
});
})
</script>
// config.js
// Load in Builder, jade, and all jQuery plugins
define(['Builder', 'jade', 'jqueryp!bootstrap!timpicker'], function (Builder, jade, $) {
// Set jade as the template engine
Builder.set('template engine', jade.render);
// Add in all jQuery plugins (Builder.jquery specific)
Builder.addPlugin('tooltip');
Builder.addPlugin({'module': 'timepicker', 'selector': '.bootstrap-timepicker'});
// Return an empty config
return {};
});
// views/index.jade
.container
if (err)
p An error occurred. =(
else
h1 User info
.row
.span6 Name: #{user.name}
.span6 Email: #{user.email}
// controllers/index.js
define(['Sauron', 'Builder', 'HtmlController', 'mvc!v/index.jade', 'mvc!m/user'],
function (Sauron, Builder, HtmlController, template) {
// Create and return our HtmlController
return HtmlController({
'name': 'index',
'start': function (cb) {
// Grab user info
Sauron.model('user').retrieve({'id': 1}, function (err, user) {
// Create data to render with
var data = {'err': err, 'user': user};
// Render the content and callback
var $html = Builder(template, data);
cb($html);
});
});
});
// models/user.js
define(['SocketModel'], function (SocketModel) {
// Forward all socket.io calls to server
return SocketModel({
'name': 'user',
'mixin': 'autoCRUD'
});
});
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.
Also, please don't edit files in the "dist" or "stage" subdirectories as they are generated via grunt. You'll find source code in the "src" subdirectory!
PhantomJS
While grunt can run the included unit tests via PhantomJS, this shouldn't be considered a substitute for the real thing. Please be sure to test the test/*.html
unit test file(s) in actual browsers.
See the Why does grunt complain that PhantomJS isn't installed? guide in the Grunt FAQ for help with installing or troubleshooting PhantomJS.
License
Copyright (c) 2013 Ensighten Licensed under the MIT license.