The UIZE JavaScript Framework provides an event mechanism that is available for all classes created using the framework. The event mechanism is implemented in the Uize base class, so any class that derives - however indirectly - from this base class can leverage this mechanismm. This, of course, also applies to widgets, since widget classes derive from the Uize.Widget base class, which derives from the Uize base class.
Events can easily be fired by any instance of any class created in the UIZE JavaScript Framework - at any arbitrary place in its code - by simply using the fireEvent instance method, as follows...
myInstance.fireEvent ('My Custom Event Name');
Code can add event handlers for events by using the addEventHandler method, as follows...
myInstance.addEventHandler (
'My Custom Event Name',
function () {/* do something here */}
);
The Uize base class provides a convenient infrastructure for supporting both static (ie. class) and instance events. Events can conveniently be fired for a class or an instance of a class, and methods are provided to every class that subclasses the Uize class to allow code to manage the registering and unregistering of event handlers at both the instance and class levels.
The syntax for registering handlers on static events is identical to registering handlers on instance events, except that the method is called on the class rather than an instance.
EXAMPLE
Uize.Widget.addEventHandler (
'Document Loaded',
function () {/* do some initializin' */}
);
Events are fired, using the fireEvent instance and static methods. They can be fired from anywhere in your code, even from deep within nested closures, so you can provide further hooks as needed without having to radically restructure your code around hook points.
When an event is fired, all handlers registered for that event are called sequentially - in the order in which they were registered. Each handler function can expect to receive a single parameter, being an object that represents the event being fired. The event object contains properties that describe the event, including some standard properties that are set by the event mechanism itself, and any arbitrary custom properties set by the code firing the event.
The event mechanism supports standard properties of the event object that are set by the event mechanism itself, such as...
PROPERTIES
| ? | name: the name of the event being fired |
| ? | source: the instance or class that originated the event |
EXAMPLE
myInstance.fireEvent ('My Custom Event Name');
For a handler that is registered for the above event, the event object will have the value 'My Custom Event Name' for its name property, and a reference to the instance myInstance for its source property. The event object is passed as the single parameter to registered handlers when they are called, so the following handler function would alert the value true, for example...
myInstance.addEventHandler (
'My Custom Event Name',
function (_event) {
alert (_event.name == 'My Custom Event Name' && _event.source == myInstance);
}
);
Not really a useful handler, but it illustrates the point.
In addition to the standard event properties, your code can add any aribitrary properties to the event object when firing an event. This is done by using the form of the fireEvent method that takes an event object as a parameter. To extend on the previous example, we could add a custom property to the event object for the 'My Custom Event Name' event, as follows...
EXAMPLE
myInstance.fireEvent ({name:'My Custom Event Name',customProperty:'some value'});
Now, the handlers for this event will be able to access the customProperty property on the event object in the same way as the standard name and source properties (as shown in the previous example). When using the above form of the fireEvent method, you must specify the name of the event you're firing by using the name property of the event object.
Because any handler for an event receives a reference to the event object, and because the fireEvent method can take a reference to an event object, it is possible to "relay" an event from one instance to another. When passing an event object reference to the fireEvent method, a previously set value for the source property is not overwritten, so subsequent handlers receiving a relayed event can always know the originating source.
EXAMPLE
myWidget.addEventHandler (
'Some Crazy Event',
function (_event) {myWidget.parent.fireEvent (_event)}
);
In the above example, whenever 'Some Crazy Event' is fired on the myWidget instance, the registered handler will relay it to its parent by calling the fireEvent method on its parent and passing the event object.