| Defined | src/core/Stratcom.js:36 |
|---|---|
| Group | Event Model |
| Extends | JX.Base |
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.
| parameters | :JX.Event | proxy | Event to dispatch. |
| return | :JX.Event | Returns the event argument. |
Dispatch a previously constructed proxy :JX.Event.
| parameters | Node | node | Node which data should be attached to. |
| object | data | Data to add to the node's metadata. | |
| return | object | Data attached to the node that is returned by JX.Stratcom.getData(). |
Add data to a node's metadata.
| parameters | Node | node | Node to add the sigil to. |
| string | sigil | Sigil to name the node with. | |
| return | void |
Add a sigil to a node.
| return | wild |
| return | :JX.Event|null | Event which is currently being dispatched, or null if there is no active dispatch. |
Retrieve the event (if any) which is currently being dispatched.
| parameters | Event | event | Native event for dispatch. |
| return | :JX.Event | Dispatched :JX.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 | Node | node | Node from which to retrieve data. |
| return | object | Data 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. |
Retrieve a node's metadata.
| parameters | Node | node | Node to test. |
| string | sigil | Sigil to check for. | |
| return | bool | True if the node has the sigil. |
Determine if a node has a specific sigil.
| parameters | string | type | Event type. |
| string|list? | path | Optionally, a sigil path to attach to the event. This is rarely meaningful for simple events. | |
| object? | data | Optionally, arbitrary data to send with the event. | |
| return | @{JX.Event} | The event object which was dispatched to listeners. The main use of this is to test whether any listeners prevented the event. |
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 @{JX.Base.invoke()} for documentation.
| parameters | string|list<string> | types | Event type (or list of event names) to listen for. For example, 'click' or ['keydown', 'keyup']. |
| wild | paths | Sigil paths to listen for this event on. See discussion in method documentation. | |
| function | func | Callback to invoke when this event is triggered. It should have the signature f(:JX.Event e). | |
| return | object | A reference to the installed listener. You can later remove the listener by calling this object's remove() method. |
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 | int | block | The datablock to merge data into. |
| dict | data | Dictionary of metadata. | |
| return | void |
Merge metadata. You must call this (even if you have no metadata) to start the Stratcom queue.
| return | bool | True if the event was stopped or prevented by another handler. |
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 | wild |
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(); });