com.ibm.mashups.iwidget
Interface iEvents

public iEvents

This interface defines methods that's used for event distribution and event management. Events service is accessible by using "this.iContext"

this.iContext.iEvents

To distribute an event:

this.iContext.iEvents.fireEvent("eventName");

Method Summary

void	fireEvent(String eventName, String payloadType, object payload) This method informs the iContext to distribute an event with proper payload and payload type
Boolean	setEvent(IEventDescription eventDesc) This method simply creates a new event definition or updates an existing event if the name already exists.
Boolean	setEvents(unknown eventDescs) Using this method will potentially allow optimizations to occur within the iContext.
Boolean	removeEvent(String eventName) This method removes an existing event description.It returns true if event is removed successfully or event doesn't exist, otherwise it returns false.
Boolean	removeEvents(unknown eventNames) This method removes specified events.It returns true if all the events are removed successfully , otherwise it returns false.
IEventDescription	getEvents(Object condition) The query method which takes a javascript object as condition, it returns a list of event descriptions which matches the given condition.
IEventDescription	createEventDescription(Object object) This method allows to create a new IEventDescription object.

Method Detail

fireEvent

void fireEvent(String eventName,
               String payloadType,
               object payload)

This method informs the iContext to distribute an event with proper payload and payload type

Parameters:

eventName - name of the event that needs to be distributed.Must not be null.

payloadType - optional,type of the payload.

payload - optional,object of the payload that needs to be distributed together with the event

setEvent

Boolean setEvent(IEventDescription eventDesc)

This method simply creates a new event definition or updates an existing event if the name already exists.
It returns true if new event is created successfully or existing event is updated successfully. It returns false if it fails to create new event or update existing event.

Parameters:

eventDesc - IEventDescription object. Must not be null.

Returns:

returns true if new event is created successfully or existing event is updated successfully. It returns false if it fails to create new event or update existing event.

setEvents

Boolean setEvents(unknown eventDescs)

Using this method will potentially allow optimizations to occur within the iContext. The returned boolean
indicates whether or not the request added all the described events to the iwidgets.

Parameters:

eventDesc - array of IEventDescription object. Must not be null.

Returns:

returns true if all the events are created successfully or existing events are updated successfully. It returns false if not all events are processed successfully.

removeEvent

Boolean removeEvent(String eventName)

This method removes an existing event description.It returns true if event is removed successfully or event doesn't exist, otherwise it returns false.

Parameters:

eventName - event name. Must not be null.

Returns:

returns true if event is removed successfully or event doesn't exist, otherwise it returns false.

removeEvents

Boolean removeEvents(unknown eventNames)

This method removes specified events.It returns true if all the events are removed successfully , otherwise it returns false.

Parameters:

eventName - event name. Must not be null.

Returns:

returns true if all the events are removed successfully, otherwise it returns false.

getEvents

IEventDescription getEvents(Object condition)

The query method which takes a javascript object as condition, it returns a list of event descriptions which matches the given condition.
The scope of the events is limited to this iwidget instance. The returning result need to match all the conditions that's given.
For exampe, if a condition object looks like this: { type:'text', isHandled:true}
This method will return all the handled event description whose payload is text.
If no condition is provided, this method will return all the events. It returns null if no event is found for a given condition.Only predefined fields or non localized attributes should be used to define condition.

Parameters:

condition - JSON object that contains the condition. Must not be null.

Returns:

returns an array of event description that matches the condition. It returns null if no event is found for a given condition.

createEventDescription

IEventDescription createEventDescription(Object object)

This method allows to create a new IEventDescription object. All the data should be passed in as a JSON object.
Following rules applied to the JSON object:
1. Predefined fields: name,type,isHandled,isPublished,lang,handlingFn
2. Localized attributes: please see sample below
3. Non-localized attributes: please see sample below
4. Lotus Mashups provides a feature to allow a widget to register a private event so this event will not be exposed to other iwidgets by the wiring interface
private attribute is used to mark an event to be a private event. please see sample below
var obj = { name:"sendData", type:"text", isHandled:"true", lang:"en", handlingFn:"onSendData",
localizedAttributes: {
"en": { "title":"mytitle_en","description":"mydescription_en"},
"fr": { "title":"mytitle_fr","description":"mydescription_fr"}
} ,
attributes: { namespace:"com.ibm.mashups", onRemoveWire:"handleRemoveWire",private:"true"}
};
var event = this.iContext.iEvents.createEventDescription(obj);
this.iContext.iEvents.setEvent(event);


Parameters:

object - JSON object that contains all the data to create an IEventDescription. Must not be null.

Returns:

returns an IEventDescription . It returns null if it fail to create the iEventDescription.