What is scaleApp?
scaleApp is a tiny JavaScript framework for scalable and maintainable
One-Page-Applications / Single-Page-Applications.
The framework allows you to easily create complex web applications.
You can dynamically start and stop/destroy modules that acts as small parts of
your whole application.
Architecture overview
scaleApp is based on a decoupled, event-driven architecture that is inspired by
the talk of Nicholas C. Zakas -
"Scalable JavaScript Application Architecture"
(Slides).
There also is a little Article that
describes the basic ideas.
Module
A module is a completely independent part of your application.
It has absolutely no reference to another piece of the app.
The only thing the module knows is your sandbox.
The sandbox is used to communicate with other parts of the application.
Sandbox
The main purpose of the sandbox is to use the
facade pattern.
In that way you can hide the features provided by the core and only show
a well defined custom static long term API to your modules.
This is actually one of the most important concept for creating
mainainable apps. Change plugins, implementations etc.
but keep your API stable for your modules.
For each module a separate sandbox will be created.
Core
The core is responsible for starting and stopping your modules.
It also handles the messages by using the
Publish/Subscribe (Mediator) pattern
Plugin
Plugins can extend the core or the sandbox with additional features.
For example you could extend the core with basic functionalities
(like DOM manipulation) or just aliases the features of a base library (e.g. jQuery).
Features
- loose coupling of modules
- small (about 300 sloc / 8,7k min / 3.3k gz)
- no dependencies
- modules can be tested separately
- replacing any module without affecting other modules
- extendable with plugins
- browser and Node.js support
- flow control
- AMD & CommonJS support
- framework-agnostic
Extendable
scaleApp itself is very small but it can be extended with plugins. There already
are some plugins available:
mvc
- simple MVCi18n
- multi language UIspermission
- take care of method accessstate
- Finite State Machinesubmodule
- cascade modulesdom
- DOM manipulationstrophe
- XMPP communicationmodulestate
- event emitter for init
and destroy
util
- helper methods like mixin
, uniqueId
etc.ls
- list modules, instances & plugins
You can easily define your own plugin (see plugin section).
Download
Latest stable 0.4.x version
or use the CDN:
<script src="//cdnjs.cloudflare.com/ajax/libs/scaleapp/0.4.4/scaleapp.min.js" ></script>
Old stable 0.3.x version
Note
There are some API changes in version 0.4.x (see Changelog).
Docs for v0.3.9 can be found within the tar/zip file.
Unstable version
git clone git://github.com/flosse/scaleApp.git
Quick Start
Link scaleApp.min.js
in your HTML file:
<script src="scaleApp.min.js"></script>
or use the CDN:
<script src="//cdnjs.cloudflare.com/ajax/libs/scaleapp/0.4.4/scaleapp.min.js" ></script>
If you're going to use it with node:
npm install scaleapp --save
var sa = require("scaleapp");
or use bower:
bower install scaleapp
Create your own Sandbox
First of all create your own sandbox.
By doing that you're able to guarantee a
stable maintainable API for your modules.
var MySandbox = function(core, instanceId, options, moduleId) {
this.myFooProperty = "bar";
core._mediator.installTo(this);
this.myEmit = function(channel, data){
core.emit(channel + '/' + instanceId, data);
};
this.id = instanceId;
return this;
};
MySandbox.prototype.foo = function() { };
Create a core
Now create a new core instance with your sandbox:
var core = new scaleApp.Core(MySandbox);
Register modules
core.register( "myModuleId", function( sandbox ){
return {
init: function(){ },
destroy: function(){ }
};
});
As you can see the module is a function that takes the sandbox as a parameter
and returns an object that has two functions init
and destroy
(the latter is
optional).
Of course your module can be any usual class with those two functions.
var MyGreatModule = function(sandbox){
return {
init: function(){ alert("Hello world!"); }
destroy: function(){ alert("Bye bye!"); }
};
};
core.register("myGreatModule", MyGreatModule);
The init
function is called by the framework when the module is supposed to
start. The destroy
function is called when the module has to shut down.
Asynchronous initialization
You can also init or destroy you module in a asynchronous way:
var MyAsyncModule = function(sandbox){
return {
init: function(options, done){
doSomethingAsync(function(err){
done(err);
});
},
destroy: function(done){
doSomethingElseAsync(done);
}
};
};
core.register("myGreatModule", MyGreatModule);
core.start("myGreatModule", { done:function(){
alert("now the initialization is done");
}});
Start modules
After your modules are registered, start your modules:
core
.start( "myModuleId" )
.start( "anOtherModule", function(err){
});
Start options
You may also want to start several instances of a module:
core.start( "myModuleId", {instanceId: "myInstanceId" } );
core.start( "myModuleId", {instanceId: "anOtherInstanceId" });
All you attach to options
is accessible within your module:
core.register( "mod", function(sandbox){
return {
init: function(opt){
(opt.myProperty === "myValue")
},
destroy: function(){ }
};
});
core.start("mod", {
instanceId: "test",
options: { myProperty: "myValue" }
});
If all your modules just needs to be instanciated once, you can simply starting
them all:
core.start();
To start some special modules at once you can pass an array with the module
names:
core.start(["moduleA","moduleB"]);
You can also pass a callback function:
core.start(function(){
});
Moreover you can use a separate sandbox for each instance:
var MySandbox = function(){};
core.start("module", { sandbox: MySandbox });
Stopping
It's obvious:
core.stop("moduleB");
core.stop();
Publish/Subscribe
If the module needs to communicate with others, you can use the emit
and
on
methods.
emit
The emit
function takes three parameters whereas the last one is optional:
topic
: the channel name you want to emit todata
: the data itselfcb
: callback method
The emit function is accessible through the sandbox
(as long as you exposed the Mediator methods of course):
sandbox.emit( "myEventTopic", myData );
on
A message handler could look like this:
var messageHandler = function( data, topic ){
switch( topic ){
case "somethingHappend":
sandbox.emit( "myEventTopic", processData(data) );
break;
case "aNiceTopic":
justProcess( data );
break;
}
};
... and it can listen to one or more channels:
sub1 = sandbox.on( "somthingHappend", messageHandler );
sub2 = sandbox.on( "aNiceTopic", messageHandler );
Or just do it at once:
sandbox.on({
topicA: cbA,
topicB: cbB,
topicC: cbC
});
You can also subscribe to several channels at once:
sandbox.on(["a", "b"], cb);
If you prefer a shorter method name you can use the alias on
.
attache and detache
A subscription can be detached and attached again:
sub.detach();
sub.attach();
Unsubscribe
You can unsubscribe a function from a channel
sandbox.off("a-channel", callback);
And you can remove a callback function from all channels
sandbox.off(callback);
Or remove all subscriptions from a channel:
sandbox.off("channelName");
Flow control
Series
var task1 = function(next){
setTimeout(function(){
console.log("task1");
next(null, "one");
},0);
};
var task2 = function(next){
console.log("task2");
next(null, "two");
};
scaleApp.util.runSeries([task1, task2], function(err, result){
});
Parallel
var task1 = function(next){
setTimeout(function(){
console.log("task1");
next(null, "a");
},0);
};
var task2 = function(next){
console.log("task2");
next(null, "b");
};
scaleApp.util.runParallel([task1, task2],function(err,result){
});
There is also a little helper tool to run the same async task
again and again in parallel for different values:
var vals = ["a","b", "c"];
var worker = function(val, next){
console.log(val);
doSomeAsyncValueProcessing(val,function(err,result){
next(err, result);
});
};
scaleApp.util.doForAll(args, worker, function(err, res){
});
Waterfall
var task1 = function(next){
setTimeout(function(){
next(null, "one", "two");
},0);
};
var task2 = function(res1, res2, next){
next(null, "yeah!");
};
scaleApp.util.runWaterfall([task1, task2], function(err, result){
});
Plugins
There are some plugins available within the plugins
folder.
For more information look at the
plugin README.
Register plugins
A single plugin can be registered with it option object in that way:
core.use(plugin,options);
If you want to register multiple plugins at once:
core.use([
plugin1,
plugin2,
{ plugin: plugin3, options: options3 }
]);
Write your own plugin
It's easy:
core.use(function(core){
core.helloWorld = function(){ alert("helloWorld"); };
};
Here a more complex example:
core.use(function(core, options, done){
core.myCoreFunction = function(){ alert("Hello core plugin") };
core.myBoringProperty = "boring";
core.Sandbox.prototype.myMethod = function(){};
var onModuleInit = function(instanceSandbox, options, done){
if (options.mySwitch){
instanceSandbox.appendFoo = function(){
core.getContainer.append("foo");
};
}
core.myAsyncMethod(function(data){
done();
});
};
var onModuleDestroy = function(done){
myCleanUpMethod(function(){
done()
});
};
return {
init: onModuleInit,
destroy: onModuleDestroy
};
});
Usage:
core.myCoreFunction()
var MyModule = function(sandbox){
init: function(){ sandbox.appendFoo(); },
};
Build browser bundles
If you want scaleApp bundled with special plugins type
grunt custom[:PLUGIN_NAME]
e.g. cake custom:dom:mvc
creates the file scaleApp.custom.js
that
contains scaleApp itself the dom plugin and the mvc plugin.
API
scaleApp
scaleApp.VERSION
- the current version of scaleAppscaleApp.Mediator
- the Mediator classscaleApp.Sandbox
- the Sandbox classscaleApp.Core
- the Core class
Core
var core = new scaleApp.Core();
var core = new scaleApp.Core(yourSandboxClass);
core.register(moduleName, module, options)
- register a modulecore.use(plugin, options)
- register a plugincore.use(pluginArray)
- registers an array of pluginscore.boot(callback)
- initialize plugins
(will be executed automatically on ´start´)core.start(moduleId, options, callback)
- start a modulecore.stop(instanceId, callback)
- stop a module
Mediator
var mediator = new scaleApp.Mediator();
var mediator = new scaleApp.Mediator(context);
var mediator = new scaleApp.Mediator(null, true);
mediator.emit(channel, data, callback)
mediator.on(channel, callback, context)
mediator.off(channel, callback)
mediator.installTo(context, force)
var subscription = mediator.on(channel, callback, context);
subscription.detach
- stop listeningsubscription.attach
- resume listening
var fn = function(){ };
var obj = { emit: fn };
mediator.installTo(obj);
obj.emit === fn
mediator.installTo(obj, true);
obj.emit === mediator.emit
Sandbox
This is the default sandbox of scaleApp.
It's a better idea to use your own one.
var sandbox = new scaleApp.Sandbox(core, instanceId, options, moduleId)` - create a Sandbox
sandbox.emit
is mediator.emit
sandbox.on
is mediator.on
sandbox.off
is mediator.off
Changelog
v0.4.4 (07-2014)
- fixed i18n plugin (not it works with the submodule plugin and a global dict)
- added i18n plugin option
global
v0.4.3 (02-2014)
- added option to
Mediator.installTo
to force overriding existing properties - added option
useGlobalMediator
to the submodule plugin - added option
mediator
to the submodule plugin - added submodule example
- fixed requireJS example
- fixed grunt task for custom builds
- strophe plugin
- expose the mediator
- fixed error emitting on failed connection
- compile with coffee-script 1.7.1
v0.4.2 (10-2013)
- fixed restarting modules
- speed up argument extraction
- little refactoring
v0.4.1 (09-2013)
- no more sandbox manipulation
- added start option to use a separate sandbox
- removed modules directory
(building modules is your own business;
above all they should depend on YOUR sandbox)
- available at cdnjs.com
- improved README
- bugfixes
v0.4.0 (07-2013)
- added a
Core
class that can be instantiated (var core = new scaleApp.Core();
) - new plugin API (
scaleApp.plugins.register
moved to core.use
)
- support asynchronous plugins
- added
boot
method to initialize asynchronous plugins
- changed API
startAll()
is now start()
stopAll()
is now stop()
- the API is now chainable (e.g.
core.use(X).register("foo",bar).start("foo")
) - removed
setInstanceOptions
- removed
unregister
and unregisterAll
- dropped
subscribe
, unsubscribe
and publish
from Mediator API
(use on
, off
and emit
instead) - the methods
lsModules
, lsInstances
, lsPlugins
moved to the ls
plugin - the
destroy
method of a module is now optional - the
callback
property of the start option object was removed.
Use the modulestate
plugin instead
- plugins
- new
submodule
plugin - improved
permission
and i18n
- new
modulestate
plugin to emit events on module state changes
- cleaner code
Mediator
: do not clone objects any more (do it manually instead)- test with mocha, chai, sinon, karma and PhantomJS instead of buster.js
v0.3.9 (12-2012)
- grunt as build systemt
- added waterfall flow control method
- improved permission plugin
- improved state plugin (thanks to Strathausen)
- added xmpp (stropje.js) plugin
- added a simple clock module
- added bower support
- added this changelog
v0.3.8 (08-2012)
- bug fixes
- added support for async. callback of the
publish
method - added amd support
v0.3.7 (07-2012)
- bug fixes
- added permission plugin
- ported specs to buster.js
- support for global i18n properties
v0.3.6 (03-2012)
- support for async. and sync. module initialization
v0.3.5 (03-2012)
v0.3.4 (03-2012)
- bugfixes
- added
lsModules
and lsInstances
- improved README
v0.3.3 (02-2012)
- run tests with jasmine-node instead of JSTestDriver
- added travis testing
- improved README
v0.3.2 (01-2012)
- bugfixes
- improved Mediator
v0.3.0 (11-2011)
- ported to Coffee-Script
- removed jQuery dependency
v0.2.0 (07-2011)
v0.1.0 (02-2011)
Testing
npm test
Demo
WARNING: the demo is totally out of date!
You can try out the sample application
that is build on scaleApp.
Also have a look at the source code.
Licence
scaleApp is licensed under the MIT license.
For more information have a look at
LICENCE.txt.