WeavyEvents

Event handling with event propagation and before and after phases.

The event system provides event-chaining with a bubbling mechanism that propagates all the way from the emitting child trigger to the root instance.

NOTE: Each weavy instance has an event handler instance exposed as weavy.events. So references to .triggerEvent() in this documentation would translate to weavy.events.triggerEvent(). For convenience the .on(), .one() and .off() functions are exposed directly on the weavy instance as weavy.on(), weavy.one() and weavy.off(). They are also exposed as child object functions on spaces and apps as space.on() and app.on() etc.

All events in the client have three phases; before, on and after. Each event phase is a prefix to the event name.

  • The before:event-name is triggered in an early stage of the event cycle and is a good point to modify event data or cancel the event.
  • The on:event-name is the normal trigger point for the event. It does not need to be prefixed when registering an event listener, you can simly use the event-name when you register a listener. This is the phase you normally use to register event listeners.
  • The after:event-name is triggered when everything is processed. This is a good point to execute code that is dependent on that all other listers have been executed.

In each phase, the event is propagated to objects in the hierarchy, much like bubbling in the DOM. The event chain always contains at least the triggering object and the root, but may have more objects in between. This means that the root will receive all events regardless of which child-object that was triggering event, but the child objects will only receive the events that they triggered themeselves or any of their child objects triggered.

  • The event chain starts at the root in the before: phase and works it's way towards the triggering child object. This gives all parent-listeners a chance to modify event data or cancel the event before it reaches the triggering child object.
  • In the on: phase the event chain starts at the trigger and goes up to the weavy instance, like rings on the water.
  • Finally, the after: phase goes back from the weavy instance and ends up at the triggering child-object at last.

Cancelling an event by calling event.stopPropagation() will stop any propagation and cause all the following phases for the event to be cancelled.

Kind: global class

.on([context], events, [selector], handler)

Registers one or several event listneres. All event listners are managed and automatically unregistered on destroy.

When listening to weavy events, you may also listen to before: and after: events by simply adding the prefix to a weavy event. Eventhandlers listening to weavy events may return modified data that is returned to the trigger. The data is passed on to the next event in the trigger event chain. If an event handler calls event.stopPropagation() or return false, the event chain will be stopped and the value is returned.

Kind: instance method of WeavyEvents
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string : Object ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, followed by any data arguments provided by the trigger.

Example (Instance event)
weavyEvents.on("before:options", function(e, options) { ... })
weavyEvents.on("options", function(e, options) { ... })
weavyEvents.on("after:options", function(e, options) { ... })
 
Example (Realtime event)
weavyEvents.on(weavy.connection, "eventname", function(e, message) { ... })
  
Example (Connection event)
weavyEvents.on(weavy.connection, "disconnect.connection", function(e) { ... })
  
Example (Button event)
weavyEvents.on(myButton, "click", function() { ... })
  
Example (Multiple document event listeners using jQuery context and selector)
weavyEvents.on($(document), "show.bs.modal hide.bs.modal", ".modal", function() { ... })

.one([context], events, [selector], handler)

Registers one or several event listneres that are executed once. All event listners are managed and automatically unregistered on destroy.

Similar to on.

Kind: instance method of WeavyEvents
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string : Object ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, folowed by any data arguments provided by the trigger.


.off([context], events, [selector], handler)

Unregisters event listneres. The arguments must match the arguments provided on registration using .on() or .one().

Kind: instance method of WeavyEvents
Category: eventhandling
ParamDescription
[context : Element ]

Context Element. If omitted it defaults to the Weavy instance. weavy.connection and wvy.postal may also be used as contexts.

events : string

One or several event names separated by spaces. You may provide any namespaces in the names or use the general namespace parameter instead.

[selector : string ]

Only applicable if the context supports selectors, for instance jQuery.on().

handler : function

The listener. The first argument is always the event, folowed by any data arguments provided by the trigger.


.clear()

Clears all registered eventhandlers

Kind: instance method of WeavyEvents
Category: eventhandling

.triggerEvent(name, [data]) ⇒ data

Trigger a custom event. Events are per default triggered on the weavy instance using the weavy namespace.

The trigger has an event chain that adds before: and after: events automatically for all events except when any custom prefix: is specified. This way you may customize the eventchain by specifying before:, on: and after: in your event name to fire them one at the time. The on: prefix will then be removed from the name when the event is fired.

Eventhandlers listening to the event may return modified data that is returned by the trigger event. The data is passed on to the next event in the trigger event chain. If an event handler calls event.stopPropagation() or return false, the event chain will be stopped and the value is returned.

Kind: instance method of WeavyEvents
Returns: data - The data passed to the event trigger including any modifications by event handlers. Returns false if the event is cancelled.
Category: eventhandling
ParamDescription
name : string

The name of the event.

[data : Array/Object/JSON ]

Data may be an array or plain object with data or a JSON encoded string.

Example
// Normal triggering
weavyEvents.triggerEvent("myevent");

// Will trigger the following events on the root instance
// 1. before:myevent.event.weavy
// 2. myevent.event.weavy
// 3. after:myevent.event.weavy
Example
// Custom triggering, one at the time
weavyEvents.triggerEvent("before:myevent");
weavyEvents.triggerEvent("on:myevent");
weavyEvents.triggerEvent("after:myevent");
Example
// Advanced triggering with data handling

function doSomething() {
    // Will trigger the events sequentially and check the response data in between

    var myTriggerData = { counter: 123, label: "my label" };

    // Custom triggering, one at the time

    // 1. Trigger before: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("before:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("before:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }

    // ...

    // 2. Continue with on: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("on:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("on:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }

    // ...

    // 3. At last trigger after: and save the response data back to myTriggerData
    myTriggerData = weavyEvents.triggerEvent("after:myevent", myTriggerData);
    
    if (myTriggerData === false) {
        console.warn("after:myevent was cancelled by event.stopPropagation() or return false");
        return;
    }
    
    console.log("myevent was fully executed", myTriggerData);
    return myTriggerData;
}