Marionette.Application.module

Marionette allows you to define a module within your application, including sub-modules hanging from that module. This is useful for creating modular, encapsulated applications that are split apart in to multiple files.

Marionette’s module allow you to have unlimited sub-modules hanging off your application, and serve as an event aggregator in themselves.

Basic Usage

A module is defined directly from an Application object as the specified name:

var MyApp = new Backbone.Marionette.Application();

var myModule = MyApp.module("MyModule");

MyApp.MyModule; // => a new Marionette.Application object

myModule === MyApp.MyModule; // => true

If you specify the same module name more than once, the first instance of the module will be retained and a new instance will not be created.

Starting And Stopping Modules

Modules can be started and stopped independently of the application and of each other. This allows them to be loaded asynchronously, and also allows them to be shut down when they are no longer needed. This also facilitates easier unit testing of modules in isolation as you can start only the module that you need in your tests.

Starting Modules

Starting a module is done in one of two ways:

  1. Automatically with the parent module (or Application) .start() method
  2. Manually call the .start() method on the module

In this example, the module will be started automatically with the parent application object’s start call:

MyApp = new Backbone.Marionette.Application();

MyApp.module("Foo", function(){

    // module code goes here

});

MyApp.start();

Note that modules loaded and defined after the app.start() call will still be started automatically.

Preventing Auto-Start Of Modules

If you wish to manually start a module instead of having the application start it, you can tell the module definition not to start with the parent:

var fooModule = MyApp.module("Foo", { startWithParent: false, define:
    function(){ // module code goes here } });

// start the app without starting the module MyApp.start();

// later, start the module fooModule.start();

Note the use of an object literal instead of just a function to define the module, and the presence of the startWithParent attribute, to tell it not to start with the application. Then to start the module, the module’s start method is manually called.

You can also grab a reference to the module at a later point in time, to start it:

MyApp.module("Foo", { startWithParent: false, define: function(){
    /*...*/ }
});

// start the module by getting a reference to it first
MyApp.module("Foo").start();

Starting Sub-Modules With Parent

Starting of sub-modules is done in a depth-first hierarchy traversal. That is, a hierarchy of Foo.Bar.Baz will start Baz first, then Bar, and finally `Foo.

Submodules default to starting with their parent module.

MyApp.module("Foo", function(){...}); MyApp.module("Foo.Bar",
function(){...});

MyApp.start();

In this example, the “Foo.Bar” module will be started with the call to MyApp.start() because the parent module, “Foo” is set to start with the app.

A sub-module can override this behavior by setting it’s startWithParent to false. This prevents it from being started by the parent’s start call.

MyApp.module("Foo", define: function(){...});

MyApp.module("Foo.Bar", { startWithParent: true, define: function(){...}});

MyApp.start();

Now the module “Foo” will be started, but the sub-module “Foo.Bar” will not be started.

A sub-module can still be started manually, with this configuration:

MyApp.module("Foo.Bar").start();

Stopping Modules

A module can be stopped, or shut down, to clear memory and resources when the module is no longer needed. Like starting of modules, stopping is done in a depth-first hierarchy traversal. That is, a hierarchy of modules like Foo.Bar.Baz will stop Baz first, then Bar, and finally Foo.

To stop a module and it’s children, call the stop() method of a module.

MyApp.module("Foo").stop();

Modules are not automatically stopped by the application. If you wish to stop one, you must call the stop method on it. The exception to this is that stopping a parent module will stop all of it’s sub-modules.

MyApp.module("Foo.Bar.Baz");

MyApp.module("Foo").stop();

This call to stop causes the Bar and Baz modules to both be stopped as they are sub-modules of Foo. For more information on defining sub-modules, see the section “Defining Sub-Modules With . Notation”.

Defining Sub-Modules With . Notation

Sub-modules or child modules can be defined as a hierarchy of modules and sub-modules all at once:

MyApp.module("Parent.Child.GrandChild");

MyApp.Parent; // => a valid module object MyApp.Parent.Child; // => a
valid module object MyApp.Parent.Child.GrandChild; // => a valid module
object

When defining sub-modules using the dot-notation, the parent modules do not need to exist. They will be created for you if they don’t exist. If they do exist, though, the existing module will be used instead of creating a new one.

Module Definitions

You can specify a callback function to provide a definition for the module. Module definitions are invoked immediately on calling module method.

The module definition callback will receive 6 parameters:

  • The module itself
  • The Parent module, or Application object that .module was called from
  • Backbone
  • Backbone.Marionette
  • jQuery
  • Underscore
  • Any custom arguments

You can add functions and data directly to your module to make them publicly accessible. You can also add private functions and data by using locally scoped variables.

MyApp.module("MyModule", function(MyModule, MyApp, Backbone, Marionette,
    $, \_){

    // Private Data And Functions // --------------------------

    var myData = "this is private data";

    var myFunction = function(){ console.log(myData); }

    // Public Data And Functions // -------------------------

    MyModule.someData = "public data";

    MyModule.someFunction = function(){ console.log(MyModule.someData); }
});

console.log(MyApp.MyModule.someData); //=> public data
MyApp.MyModule.someFunction(); //=> public data

Module Initializers

Modules have initializers, similarly to Application objects. A module’s initializers are run when the module is started.

MyApp.module("Foo", function(Foo){

    Foo.addInitializer(function(){
        // initialize and start the module's running code, here.
    });

});

Any way of starting this module will cause it’s initializers to run. You can have as many initializers for a module as you wish.

Module Finalizers

Modules also have finalizers that are run when a module is stopped.

MyApp.module("Foo", function(Foo){

    Foo.addFinalizer(function(){
        // tear down, shut down and clean up the module, here
    });

});

Calling the stop method on the module will run all that module’s finalizers. A module can have as many finalizers as you wish.

The Module’s this Argument

The module’s this argument is set to the module itself.

MyApp.module("Foo", function(Foo){   this === Foo; //=> true });

Custom Arguments

You can provide any number of custom arguments to your module, after the module definition function. This will allow you to import 3rd party libraries, and other resources that you want to have locally scoped to your module.

MyApp.module("MyModule", function(MyModule, MyApp, Backbone, Marionette, $,
    \_, Lib1, Lib2, LibEtc){

    // Lib1 === LibraryNumber1; // Lib2 === LibraryNumber2; // LibEtc ===
    LibraryNumberEtc;

}, LibraryNumber1, LibraryNumber2, LibraryNumberEtc);

Splitting A Module Definition Apart

Sometimes a module gets to be too long for a single file. In this case, you can split a module definition across multiple files:

MyApp.module("MyModule", function(MyModule){
    MyModule.definition1 = true; });

MyApp.module("MyModule", function(MyModule){ MyModule.definition2 =
true; });

MyApp.MyModule.definition1; //=> true MyApp.MyModule.definition2; //=>
true