scaleapp

scaleApp is a JavaScript framework for scalable and maintainable One-Page-Applications

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.

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.

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.

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.

The core is responsible for starting and stopping your modules. It also handles the messages by using the Publish/Subscribe (Mediator) pattern

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).

  • 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

scaleApp itself is very small but it can be extended with plugins. There already are some plugins available:

  • mvc - simple MVC
  • i18n - multi language UIs
  • permission - take care of method access
  • state - Finite State Machine
  • submodule - cascade modules
  • dom - DOM manipulation
  • strophe - XMPP communication
  • modulestate - 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

or use the CDN:

<script src="//cdnjs.cloudflare.com/ajax/libs/scaleapp/0.4.4/scaleapp.min.js" ></script>

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.

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

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(coreinstanceIdoptionsmoduleId) {
 
  // define your API 
  this.myFooProperty = "bar";
 
  // e.g. provide the Mediator methods 'on', 'emit', etc. 
  core._mediator.installTo(this);
 
  // ... or define your custom communication methods 
  this.myEmit = function(channeldata){
    core.emit(channel + '/' + instanceId, data);
  };
 
  // maybe you'd like to expose the instance ID 
  this.id = instanceId;
 
  return this;
};
 
// ... and of course you can define shared methods etc. 
MySandbox.prototype.foo = function() { /*...*/ };

Now create a new core instance with your sandbox:

var core = new scaleApp.Core(MySandbox);
core.register( "myModuleId", function( sandbox ){
  return {
    init:    function(){ /*...*/ },
    destroyfunction(){ /*...*/ }
  };
});

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!"); }
    destroyfunction(){ 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.

You can also init or destroy you module in a asynchronous way:

var MyAsyncModule = function(sandbox){
  return {
    initfunction(optionsdone){
      doSomethingAsync(function(err){
        // ... 
        done(err);
      });
    },
    destroyfunction(done){
      doSomethingElseAsync(done);
    }
  };
};
 
core.register("myGreatModule", MyGreatModule);
core.start("myGreatModule", { done:function(){
  alert("now the initialization is done");
}});

After your modules are registered, start your modules:

core
  .start( "myModuleId" )
  .start( "anOtherModule", function(err){
    // 'anOtherModule' is running now 
  });

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 {
    initfunction(opt){
      (opt.myProperty === "myValue")  // true 
    },
    destroyfunction(){ /*...*/ }
  };
});
 
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(){
  // do something when all modules were initialized 
});

Moreover you can use a separate sandbox for each instance:

var MySandbox = function(){/*...*/};
core.start("module", { sandbox: MySandbox });

It's obvious:

core.stop("moduleB");
core.stop(); // stops all running instances 

If the module needs to communicate with others, you can use the emit and on methods.

The emit function takes three parameters whereas the last one is optional:

  • topic : the channel name you want to emit to
  • data : the data itself
  • cb : callback method

The emit function is accessible through the sandbox (as long as you exposed the Mediator methods of course):

sandbox.emit( "myEventTopic", myData );

A message handler could look like this:

var messageHandler = function( datatopic ){
  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.

A subscription can be detached and attached again:

sub.detach(); // don't listen any more 
sub.attach(); // receive upcoming messages 

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");
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(errresult){
  // result is ["one", "two"] 
});
 
// console output is: 
// "task1" 
// "task2" 
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){
  // result is ["a", "b"] 
});
 
// console output is: 
// "task2" 
// "task1" 

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(valnext){
  console.log(val);
  doSomeAsyncValueProcessing(val,function(err,result){
    next(err, result);
  });
};
 
scaleApp.util.doForAll(args, worker, function(errres){
  // fini 
});
var task1 = function(next){
  setTimeout(function(){
    next(null, "one", "two");
  },0);
};
 
var task2 = function(res1res2next){
  // res1 is "one" 
  // res2 is "two" 
  next(null, "yeah!");
};
 
scaleApp.util.runWaterfall([task1, task2], function(errresult){
  // result is "yeah!" 
});

There are some plugins available within the plugins folder. For more information look at the plugin README.

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 }
]);

It's easy:

core.use(function(core){
  core.helloWorld = function(){ alert("helloWorld"); };
};

Here a more complex example:

core.use(function(coreoptionsdone){
 
  // extend the core 
  core.myCoreFunction = function(){ alert("Hello core plugin") };
  core.myBoringProperty = "boring";
 
  // extend the sandbox class 
  core.Sandbox.prototype.myMethod = function(){/*...*/};
 
  // define a method that gets called when a module starts 
  var onModuleInit = function(instanceSandboxoptionsdone){
 
    // e.g. define sandbox methods dynamically 
    if (options.mySwitch){
      instanceSandbox.appendFoo = function(){
       core.getContainer.append("foo");
      };
    }
 
    // or load a something asynchronously 
    core.myAsyncMethod(function(data){
 
      // do something... 
      // now tell scaleApp that you're done 
      done();
    });
  };
 
  // define a method that gets called when a module stops 
  var onModuleDestroy = function(done){
    myCleanUpMethod(function(){
      done()
    });
  };
 
  // don't forget to return your methods 
  return {
    init: onModuleInit,
    destroy: onModuleDestroy
  };
 
});

Usage:

core.myCoreFunction() // alerts "Hello core plugin" 
 
var MyModule = function(sandbox){
  initfunction(){ sandbox.appendFoo(); },  // appends "foo" to the container 
};

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.VERSION - the current version of scaleApp
  • scaleApp.Mediator - the Mediator class
  • scaleApp.Sandbox - the Sandbox class
  • scaleApp.Core - the Core class
// use default sandbox 
var core = new scaleApp.Core();
 
// use your own sandbox 
var core = new scaleApp.Core(yourSandboxClass);
  • core.register(moduleName, module, options) - register a module
  • core.use(plugin, options) - register a plugin
  • core.use(pluginArray) - registers an array of plugins
  • core.boot(callback) - initialize plugins (will be executed automatically on ´start´)
  • core.start(moduleId, options, callback) - start a module
  • core.stop(instanceId, callback) - stop a module
// create a mediator 
var mediator = new scaleApp.Mediator();
 
// create a mediator with a custom context object 
var mediator = new scaleApp.Mediator(context);
 
// create a mediator with cascaded channels 
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)
// subscribe 
var subscription = mediator.on(channel, callback, context);
  • subscription.detach - stop listening
  • subscription.attach - resume listening
var fn  = function(){ /*...*/ };
var obj = { emit: fn };
 
// the installTo method prevents existing properties by default 
mediator.installTo(obj);
obj.emit === fn // true 
 
// set the second paramater to 'true' 
// to force the mediator to override existing propeties 
mediator.installTo(obj, true);
obj.emit === mediator.emit // true 

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

  • fixed i18n plugin (not it works with the submodule plugin and a global dict)
  • added i18n plugin option global
  • 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
  • fixed restarting modules
  • speed up argument extraction
  • little refactoring
  • 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
  • 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
  • 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
  • bug fixes
  • added support for async. callback of the publish method
  • added amd support
  • bug fixes
  • added permission plugin
  • ported specs to buster.js
  • support for global i18n properties
  • support for async. and sync. module initialization
  • simpified Mediator code
  • bugfixes
  • added lsModules and lsInstances
  • improved README
  • run tests with jasmine-node instead of JSTestDriver
  • added travis testing
  • improved README
  • bugfixes
  • improved Mediator
  • ported to Coffee-Script
  • removed jQuery dependency
  • bugfixes
  • improvements
  • first release

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.