Client events

Weavy provides many events on different levels. The event system provides event-chaining with a bubbling mechanism that propagates all the way from the emitting trigger to the weavy instance. All event listeners are cleaned up automatically when you destroy the weavy instance.

Many of the events have corresponding Promises that provides a more reliable way of reacting to things happening. Unlike events events, promises will always trigger your handler even if the event just happened.

Event phases

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.

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

Event chaining

In each phase, the event is traversing objects in the hierarchy, much like bubbling in the DOM. The event chain always contains at least the triggering object and the weavy instance, but may have more objects in between. This means that the weavy instance 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 weavy instance 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.

You may break the event chain at any point by calling event.stopPropagation() or return false.

Registering event listeners

.on() .one() and .off()

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

Weavy has .on() event registration both on the weavy instance and directly on spaces and apps. You may also use .one() to automatically unregister the event listener after next trigger. To unregister the event, use .off()using the same parameters as you used in .on() or .one().

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

Param Description
[context : Element ]

Context Object. If omitted it defaults to the object that the on-method belongs to, like the weavy-instance. Use this paramaeter to enable the automatic cleanup for event listeners on external objects that essentialy belong to the weavy-instance.

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 example when using jQuery.

handler : function

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

Weavy instance event
weavy.on("before:options", function(e, options) { ... })
weavy.on("options", function(e, options) { ... })
weavy.on("after:options", function(e, options) { ... })
Button event
weavy.on(myButton, "click", function(e) { ... })
Multiple document event listeners using jQuery context
weavy.on($(document), "show.bs.modal hide.bs.modal", ".modal", function(e) { ... })

Modifying event data

At any phase or any point in the event chain you may modify the event data. You can simply return the modified data in your event listener, which then will be passed on the following listeners in the event chain.

Anything you return from your event listener will be treated as modified event data, so be careful in what you return. Also, returning false will break the chain.
weavy.on("before:badge", function (e, badge) {
    var numberOfLikes = getLikesSomewhere().length;
    badge.likes = numberOfLikes;
    badge.total += numberOfLikes;
    return badge;
});

List of events

Weavy instance events

These events are triggered directly on the instance. All other events within the instance will also propagate up to the instance.

initThe weavy instance is initialized.
loadThe server data has been loaded and the UI has been built. Related to weavy.whenLoaded() promise.
frame-checkThe frame functionality has been checked. Related to weavy.whenReady() promise.
destroyThe weavy instance is destroyed.
badgeThe user has a new message or notification. Contains data about the number of unread conversations and the number of unread notifications.
user-errorA vaild user could not be established.
signing-inThe signing in proccess has started.
signed-inThe user has successfully been signed in.
clear-userThe user is unauthenticated and data should be cleared.
signed-outThe user has signed out.
authentication-errorAuthorization was denied or authentication failed.
create-rootA DOM shadow root has been created.
remove-rootA DOM shadow root has been removed.
navigateTriggered when a navigation betweeen apps is performed. See navigation.
historyTriggered when a history point is set. See history and deep linking.

App events

All app events contains data with reference to the space and the app itself.

openThe app panel is opened.
toggleThe app panel is toggled. Is always followed by either open event or close event.
closeThe app panel is closed.