Part II - Creating Event Type

This tutorial will guide you through a series of steps explaining how you create a custom Event Type and register it with Ample SDK Framework.

• Setting up custom event type
  • Defining event type constructor
  • Defining interface name
  • Defining custom APIs
  • Defining initialization method
  • Registering event type with framework
• Using new event type

Setting up custom event type

The standard DOM Events module defines a set of basic Event Types, such as Event, UIEvent, MouseEvent, CustomEvent etc. Although the built-in CustomEvent type may be sufficient in most of the situations, some custom DOM extension, such as custom UI language, or a plugin, may require a specialized type which is not available. The new event type should then properly integrate with overal DOM Events mechanism in Ample SDK.

Please note the difference between an "Event Type" and an "event": there can be multiple events of same Event Type, for example: "mousedown" and "click" events are both of "MouseEvent" type.

Defining event type constructor

Event type constructor is usually an empty bodied function, that needs always to contain base Event object in its prototype chain.

// Define constructor
var MyEventType = function() {
        // Empty, as initializer should be implemented in specialized method
};
// Specify this type inherits from basic DOM Event type
MyEventType.prototype   = new ample.classes.Event;

Defining interface name

In order to later on properly integrate the new event type with Ample SDK, its prototype "eventInterface" property must have a string value - name of the type to be used when instantiating an event object using DOM's createEvent method. Here, eventInterface name is the Event Type name, and not the concrete event name. (Also note, event interface name and constructor name look similar in our case only by accidence, they don't have to be same).

MyEventType.prototype.eventInterface    = "MyEventType";

Defining custom APIs

You can prototype any custom members for the new type including methods and properties, be aware though of the inherited members of base Event type we inherit from. In our example we add one property called "data".

// Define custom property to be used to pass data
MyEventType.prototype.data      = null;

Defining initialization method

As per DOM Events specification, before dispatching an event object it needs to be initialized with parameters instructing the implementation about how to propagate the event. These basic parameters should be passed into inherited "initEvent" method, if a custom implementation wraps it around like below.

MyEventType.prototype.initMyEventType   = function(sType, bCanBubble, bCancelable, vData) {
        // Call parent class initializer with 3 first arguments
        this.initEvent(sType, bCanBubble, bCancellable);
        // Set own data property
        this.data       = vData;
}

Registering event type with framework

The last step you need to undertake in order to integrate your new event type into framework is to register it with the framework using ample.extend function.

ample.extend(MyEventType);

Using new event type

Now, let's see how the newly created event type could be used in the application, or in a UI Element implementation.

// Creating event object
var oMyEvent    = ample.createEvent("MyEventType");
// Initializing event (we can initialize "myotherevent", "mynotification" or other event of "MyEventType" interface)
oMyEvent.initMyEventType("myevent", true, true, "value");
// Dispatching event
ample.documentElement.dispatchEvent(oMyEvent);

If there was an event listener attached to a node on the way of the event propagation, it would be invoked in due time and its logic would be able to read the data property value.