Introduction

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) { ... })