Events

Both CloudWall core, buckets and running apps emit events, using different mechanisms and channels. There are 3 basic mechanisms:

• $.my radio broadcast events, emitted by CloudWall and apps
  
• EventEmitter instances, returned by API methods marked with ⚐ sign
• DOM events, mostly UI related, emitted by apps and controls.
  

Each mechanism has own specifics and described separately.

$.my radio events

This pub/sub mechanism is part of jquery.my framework, it guarantees that events will never reach listeners bound to removed DOM nodes.

Event may be raised from anywhere in the code, however event listeners are only available inside $.my applications.

Below reference is organized by event type emitted.

"settings.cw"

Listener receives list of buckets which settings were just updated.

"sync.cw"

Emitted when replication event just happened. Listeners receive object with string props .db , which is bucket name, and .evt, which is short state change notice, like "start" or "finish".

"slot.cw"

Emitted when slot (running app) changes state. Listener receives object with .domid and .event strings. The event property may have values like:

• "busy" slot is busy
  
• "start.dominit" slot is starting an app
  
• "start.appstart" slot successfully initialized an app
  
• "start.slotready" slot is ready and visible
  
• "start.fail" slot start failed.
  

EventEmitter feeds

CloudWall includes EventEmitter polyfill, since EE is missing in browser environment. Some bucket and app runtime methods return EventEmitter instances. 

Unlike $.my.radio pub/sub, EventEmitter subscribers may lay outside volatile CloudWall apps, and be kind of resident. 

cw.event( arg ) ⚐

Global event feed pub/sub. If argument is a string , all global listeners of the "progress" event receive this string. If argument is a function, it becomes a listener of global "progress" events feed. 

If no argument provided, returns EventEmitter object.

There are several system emitted "progress" events. They generally just notifies subscribers, that system state changed, without pointing reason or event source — it’s an agreement for broadcasted events.

Events, broadcasted by system, are:

• slot open Some app just started
• slot close Some app just closed
• db replication started Tried to start replication
• db replication failed Replication just closed or couldn’t start
• settings update Received doc with profile settings update
• app manifest update System received and mounted app manifest update.

cw.db(dbid).changes(opts) ⚐

Returns EventEmitter instance, which emits "change", "error" and "complete" events. Event source is cancellable.

cw.db(dbid).watch(docType) ⚐

Returns EventEmitter instance, which raises progress event when doc(s) of docType were just changed. If no docType provided, watcher called on any doc change.

Event listeners receive a list of changed docs.

Unlike native Pouch db.on('evt', fn), listeners mounted using watch().progress() are called with a little debounce, and receive an array to avoid jitter. 

this.db.watch(docType) ⚐

App runtime method. Returns EventEmitter instance, which raises progress event when doc(s) of docType were just changed. If no docType provided, watcher called on any doc change.

Event listener receives a list of changed docs if app is active (visible), or on app activation. If app is inactive, doc list is stashed to deliver entire pile later when app gets focus.

This allows postponed redraw of inactive apps.

DOM events

There are several CloudWall-specific DOM events, which might be useful.