Page MenuHomeGitPull.it
Diviner Javelin Docs JX.Stratcom

class JX.Stratcom
Javelin Documentation ()

Javelin strategic command, the master event delegation core. This class is a sort of hybrid between Arbiter and traditional event delegation, and serves to route event information to handlers in a general way.

Each Javelin :JX.Event has a 'type', which may be a normal Javascript type (for instance, a click or a keypress) or an application-defined type. It also has a "path", based on the path in the DOM from the root node to the event target. Note that, while the type is required, the path may be empty (it often will be for application-defined events which do not originate from the DOM).

The path is determined by walking down the tree to the event target and looking for nodes that have been tagged with metadata. These names are used to build the event path, and unnamed nodes are ignored. Each named node may also have data attached to it.

Listeners specify one or more event types they are interested in handling, and, optionally, one or more paths. A listener will only receive events which occurred on paths it is listening to. See listen() for more details.

Tasks

Builtin Events

No methods for this task.

Invoking Events

  • static invoke(type, path, data) — Dispatch a simple event that does not have a corresponding native event object. It is unusual to call this directly. Generally, you will instead dispatch events from an object using the invoke() method present on all objects. See @{method:invoke} in @{class:JX.Base} for documentation.

Listening to Events

  • static listen(types, paths, func) — Listen for events on given paths. Specify one or more event types, and zero or more paths to filter on. If you don't specify a path, you will receive all events of the given type:

Responding to Events

  • static pass() — Pass on an event, allowing other handlers to process it. The use case here is generally something like:
  • static context() — Retrieve the event (if any) which is currently being dispatched.

Managing Sigils

  • static hasSigil(node, sigil) — Determine if a node has a specific sigil.
  • static addSigil(node, sigil) — Add a sigil to a node.

Managing Metadata

  • static getData(node) — Retrieve a node's metadata.
  • static addData(node, data) — Add data to a node's metadata.

Internals

  • static dispatch(event) — Dispatch a native Javascript event through the Stratcom control flow. Generally, this is automatically called for you by the master dispatcher installed by ##init.js##. When you want to dispatch an application event, you should instead call invoke().
  • private static _dispatchProxy(proxy) — Dispatch a previously constructed proxy :JX.Event.
  • static mergeData(block, data) — Merge metadata. You must call this (even if you have no metadata) to start the Stratcom queue.
  • static allocateMetadataBlock()

remove

  • static removeCurrentListener() — Sometimes you may be interested in removing a listener directly from it's handler. This is possible by calling JX.Stratcom.removeCurrentListener()

Other Methods

Methods

static invoke(type, path, data)

JX.Base

Invoke a class event, notifying all listeners. You must declare the events your class invokes when you install it; see JX.install() for documentation. Any arguments you provide will be passed to listener callbacks.

JX.Stratcom

Dispatch a simple event that does not have a corresponding native event object. It is unusual to call this directly. Generally, you will instead dispatch events from an object using the invoke() method present on all objects. See invoke() in JX.Base for documentation.

Parameters
stringtypeEvent type, must be declared when class is installed.
...moreZero or more arguments.
Return
JX.EventThe event object which was dispatched to listeners. The main use of this is to test whether any listeners prevented the event.

static listen(types, paths, func)

JX.Base

Listen for events emitted by this object instance. You can also use the static flavor of this method to listen to events emitted by any instance of this object.

See also listen() in JX.Stratcom.

JX.Base

Static listen interface for listening to events produced by any instance of this class. See listen() for documentation.

JX.Stratcom

Listen for events on given paths. Specify one or more event types, and zero or more paths to filter on. If you don't specify a path, you will receive all events of the given type:

// Listen to all clicks.
JX.Stratcom.listen('click', null, handler);

This will notify you of all clicks anywhere in the document (unless they are intercepted and killed by a higher priority handler before they get to you).

Often, you may be interested in only clicks on certain elements. You can specify the paths you're interested in to filter out events which you do not want to be notified of.

//  Listen to all clicks inside elements annotated "news-feed".
JX.Stratcom.listen('click', 'news-feed', handler);

By adding more elements to the path, you can create a finer-tuned filter:

//  Listen to only "like" clicks inside "news-feed".
JX.Stratcom.listen('click', ['news-feed', 'like'], handler);

TODO: Further explain these shenanigans.

Parameters
stringtypeType of event to listen for.
functioncallbackFunction to call when this event occurs.
Return
objectA reference to the installed listener. You can later remove the listener by calling this object's remove() method.

static removeCurrentListener()

Sometimes you may be interested in removing a listener directly from it's handler. This is possible by calling JX.Stratcom.removeCurrentListener()

// Listen to only the first click on the page
JX.Stratcom.listen('click', null, function() {
  // do interesting things
  JX.Stratcom.removeCurrentListener();
});

static dispatch(event)

Dispatch a native Javascript event through the Stratcom control flow. Generally, this is automatically called for you by the master dispatcher installed by init.js. When you want to dispatch an application event, you should instead call invoke().

Parameters
EventeventNative event for dispatch.
Return
:JX.EventDispatched :JX.Event.

private static _dispatchProxy(proxy)

Dispatch a previously constructed proxy :JX.Event.

Parameters
:JX.EventproxyEvent to dispatch.
Return
:JX.EventReturns the event argument.

static pass()

Pass on an event, allowing other handlers to process it. The use case here is generally something like:

if (JX.Stratcom.pass()) {
  // something else handled the event
  return;
}
// handle the event
event.prevent();

This allows you to install event handlers that operate at a lower effective priority, and provide a default behavior which is overridable by listeners.

Return
boolTrue if the event was stopped or prevented by another handler.

static context()

Retrieve the event (if any) which is currently being dispatched.

Return
:JX.Event|nullEvent which is currently being dispatched, or null if there is no active dispatch.

static initialize(initializers)

This method is not documented.
Parameters
initializers

static mergeData(block, data)

Merge metadata. You must call this (even if you have no metadata) to start the Stratcom queue.

Parameters
intblockThe datablock to merge data into.
dictdataDictionary of metadata.
Return
void

static hasSigil(node, sigil)

Determine if a node has a specific sigil.

Parameters
NodenodeNode to test.
stringsigilSigil to check for.
Return
boolTrue if the node has the sigil.

static addSigil(node, sigil)

Add a sigil to a node.

Parameters
NodenodeNode to add the sigil to.
stringsigilSigil to name the node with.
Return
void

static getData(node)

Retrieve a node's metadata.

Parameters
NodenodeNode from which to retrieve data.
Return
objectData attached to the node. If no data has been attached to the node yet, an empty object will be returned, but subsequent calls to this method will always retrieve the same object.

static addData(node, data)

Add data to a node's metadata.

Parameters
NodenodeNode which data should be attached to.
objectdataData to add to the node's metadata.
Return
objectData attached to the node that is returned by JX.Stratcom.getData().

static allocateMetadataBlock()

This method is not documented.
Defined
core/Stratcom.js:42
Extends
JX.Base
Public contents are in Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) or GNU Free Documentation License (at your option) unless otherwise noted. · Contact / Register