Gaia/System/NewModule

From MozillaWiki
< Gaia‎ | System
Jump to: navigation, search

If you want to add a new functionality, a.k.a., a new script or a new module into system app after bug 1094759, please read this.

If you want to use BaseModule

Great! It's providing a promise based start procedure and what you need to do.

 var NewModule = function() {};
 BaseModule.create(NewModule, {
   name: 'NewModule',
   _start: function() {
     // return a promise if your start progress involves some asynchronous operation
     // return null or do not return, then we will unblock your module from the starting process right away once
     // yourModule.start() is called
     // BaseModule has a native start() function to process not only your own starting (this._start()) but also the child
     // module's start() function. The whole starting process will be resolved only when all the children's start process
     // is resolved.
   }
 });

If you don't want to use BaseModule

It's okay. But you have to provide this interface for us:

 var NewModule = {
   start: function() {
     // return a promise if your start progress involves some asynchronous operation
     // return null or do not return, then we will unblock your module from the starting process right away once
     // yourModule.start() is called
   }
 };

No matter what you choose to go

Don't put your new script in the header of system app. If it's necessary to go alive when booting, please find a proper parent module and lazy load it.

If the parent module is based on BaseModule

  1. Put the module in the parent module's SUB_MODULES if you think it's blocking the starting progress of the parent module.
  2. If the new module is not as important to block the parent, use this.loadWhenIdle([NEW_MODULE]) in parent's start function
  3. If the new module is only serving some on demand request, consider to lazy load the new module in the parent module's event handler and start it.

If the parent module is not based on BaseModule

  1. Lazy load the module in the parent module's start function and return a promise including the promise of the lazy loader
  2. If the new module is only serving some on demand request, consider to lazy load the new module in the parent module's event handler and start it.

Samples

In the following sample, 1. Core is an existing module who blocks the first view 2. ParentModule is an existing module who does not block the first view

Sample for the module which does block the first view and the parent module is a base module

 // ftu_loader.js
 var FtuLoader = function() {};
 BaseModule.create(FtuLoader, {
   name: 'FtuLoader',
   _start: function() {
     return LazyLoader.load('shared/js/test.js').then(() => {
       // Do something...
     });
   }
 });
 // core.js
 Core.SUB_MODULES = ['FtuLoader'];

Sample for the child module which does not block the first view and the parent module is a base module

 // side_tester.js
 var SideTester = function() {};
 BaseModule.create(SideTester, {
   name: 'SideTester',
   _start: function() {
     return LazyLoader.load('shared/js/async.js').then(() => {
       // Do something...
     });
   }
 });
 // core.js
 BaseModule.create(Core, {
   _start = function() {
     return this.loadWhenIdle(['SideTester']);
   };
 });

Sample for the new module which does not block the first view and the parent is not a baseModule

 // side_tester.js
 var ChildModule = function() {};
 ChildModule.prototype.start = function() {};
 // parent_module.js
 ParentModule.prototype.start = function() {
   return Service.request('schedule', () => {  // This is exactly what BaseModule.prototype.loadWhenIdle does
     return LazyLoader.load('child_module.js');
   }).then(() => {
     this.child = new ChildModule();
     return this.child.start();
   });
 };