EventProxy
EventProxy provides a protected proxy of another TyphonEvents / eventbus instance.
The main use case of EventProxy is to allow indirect access to an eventbus. This is handy when it comes to managing
the event lifecycle for a plugin system. When a plugin is added it could receive a callback, perhaps named
onPluginLoaded, which contains an EventProxy instance rather than the direct eventbus. This EventProxy instance is
associated in the management system controlling plugin lifecycle. When a plugin is removed / unloaded the management
system can automatically unregister all events for the plugin without requiring the plugin author doing it correctly
if they had full control. IE This allows to plugin system to guarantee no dangling listeners.
EventProxy provides the on / off, once, and trigger methods with the same signatures as found in
TyphonEvents / Events. However, the proxy has an internal Events instance which is used to proxy between the target
eventbus which is passed in from the constructor. All registration methods (on / off / once) proxy through the
internal Events instance using 'listenTo', 'listenToOnce', and 'stopListening'. In addition there is a destroy
method which will unregister all of proxies events and remove references to the managed eventbus. Any further usage
of a destroyed EventProxy instance results in a ReferenceError thrown.
Constructor Summary
| Public Constructor | ||
| public |
constructor(eventbus: TyphonEvents) Creates the event proxy with an existing instance of TyphonEvents. |
|
Member Summary
| Private Members | ||
| private |
Stores the target eventbus. |
|
| private |
Stores the proxy instance which manages all event binding with the target eventbus. |
|
Method Summary
| Public Methods | ||
| public |
destroy() Unregisters all proxied events from the target eventbus and removes any local references. |
|
| public |
getEventbusName(): string | * Returns the target eventbus name. |
|
| public |
off(name: string, callback: function, context: object): EventProxy Remove a previously-bound callback function from an object. |
|
| public |
on(name: string, callback: function, context: object): EventProxy Bind a callback function to an object. |
|
| public |
once(name: string, callback: function, context: object): EventProxy Just like |
|
| public |
Trigger callbacks for the given event, or space-delimited list of events. |
|
| public |
Provides |
|
| public |
Defers invoking |
|
| public |
triggerSync(): * | Array<*> Provides |
|
Public Constructors
public constructor(eventbus: TyphonEvents) source
Creates the event proxy with an existing instance of TyphonEvents.
Params:
| Name | Type | Attribute | Description |
| eventbus | TyphonEvents | The target eventbus instance. |
Private Members
private _proxy: TyphonEvents source
Stores the proxy instance which manages all event binding with the target eventbus.
Public Methods
public destroy() source
Unregisters all proxied events from the target eventbus and removes any local references. All subsequent calls
after destroy has been called result in a ReferenceError thrown.
public off(name: string, callback: function, context: object): EventProxy source
Remove a previously-bound callback function from an object. This is proxied through stopListening of an
internal Events instance instead of directly modifying the target eventbus.
Please see Events#off.
public on(name: string, callback: function, context: object): EventProxy source
Bind a callback function to an object. The callback will be invoked whenever the event is fired. If you have a large number of different events on a page, the convention is to use colons to namespace them: "poll:start", or "change:selection".
This is proxied through listenTo of an internal Events instance instead of directly modifying the target
eventbus.
Please see Events#on.
public once(name: string, callback: function, context: object): EventProxy source
Just like on, but causes the bound callback to fire only once before being removed. Handy for saying "the next
time that X happens, do this". When multiple events are passed in using the space separated syntax, the event
will fire once for every event you passed in, not once for a combination of all events
This is proxied through listenToOnce of an internal Events instance instead of directly modifying the target
eventbus.
Please see Events#once.
public trigger(): EventProxy source
Trigger callbacks for the given event, or space-delimited list of events. Subsequent arguments to trigger will be passed along to the event callbacks.
Please see Events#trigger.
public triggerAsync(): Promise source
Provides trigger functionality, but collects any returned Promises from invoked targets and returns a
single Promise generated by Promise.resolve for a single value or Promise.all for multiple results. This is
a very useful mechanism to invoke asynchronous operations over an eventbus.
Please see TyphonEvents#triggerAsync.
public triggerDefer(): EventProxy source
Defers invoking trigger. This is useful for triggering events in the next clock tick.
Please see TyphonEvents#triggerDefer.
public triggerSync(): * | Array<*> source
Provides trigger functionality, but collects any returned result or results from invoked targets as a single
value or in an array and passes it back to the callee in a synchronous manner.
Please see TyphonEvents#triggerSync.