Understand cordova channel event handler

Javascript supports common event handling with addEventListener and dispatchEvent methods. The event is defined on a particular object, such as document or window object. This limits the case when different objects want to have a shared event subscription manager.

For this purpose, cordova implemented a channel module to manage the event. Different modules can create their own named events (channels), but those events are handled by a shared cordova channel object.

Modules need to first call the below method to access the shared cordava channel object
  var channel = require('cordova/channel'),

With the channel object, it can call create or createStick method to create a named channel (event).
   var namedChannel = channel.create('myChannel');

The create/createStick method are the only method exposed by channel module, which can be used to create named channel instance, this is similar to the Factory pattern. As all named channel lives in the same shared cordova channel object, be sure the name is unique when creating the named channel.

Although named channel all lives in the shared channel object, they are not visible to external caller, so the module which creates the named channel instance should keep a variable reference to it, usually the channels are saved in a channels dictionary with channel name as key, and channel object as value. The owner of the named channel object then exposes APIs to allow other modules to call the instance method on the namedChannel object to subscribe, unsubscribe, or fire the event on the named channel.

For the document object, cordova.js already created few cordova common events, like onDeviceReady, etc, so other modules can use them to get cordova notification events. However, in this case, caller can directly call the javascript addEventListener method to subscribe a event without going through the cordova channel APIs. The reason is Cordova.js already override the document.addEventListener method, so it checks if the matched event name is created by cordova channel API, then it will be handled by cordova channel module, otherwise, it will be handled by default javascript addEventListener method.