Event Class
Class to support basic event publication and subscription semantics.
Item Index
Methods
- <ctor> Event
- enable static
- isEnabled static
- publish
- publishAsync
- subscribe
- unsubscribe
Methods
<ctor> Event
-
name
-
publisher
-
[defaultErrorCallback]
Constructor for an Event
Parameters:
-
name
String -
publisher
ObjectThe object that will be doing the publication. i.e. the object to which this event is attached.
-
[defaultErrorCallback]
Function optionalIf omitted then subscriber notification failures will be ignored.
errorCallback([e])
-
[e]
Error optionalAny error encountered during subscription execution.
-
Example:
salaryEvent = new Event("salaryEvent", person);
enable
-
eventName
-
target
-
isEnabled
Enables or disables the named event for an object and all of its children.
Parameters:
-
eventName
StringThe name of the event.
-
target
ObjectThe object at which enabling or disabling will occur. All event notifications that occur to this object or children of this object will be enabled or disabled.
-
isEnabled
Boolean | Null | FunctionA boolean, a null or a function that returns either a boolean or a null.
Example:
Event.enable(“propertyChanged”, myEntityManager, false)
will disable all EntityAspect.propertyChanged events within a EntityManager.
Event.enable(“propertyChanged”, myEntityManager, true)
will enable all EntityAspect.propertyChanged events within a EntityManager.
Event.enable(“propertyChanged”, myEntity.entityAspect, false)
will disable EntityAspect.propertyChanged events for a specific entity.
Event.enable(“propertyChanged”, myEntity.entityAspect, null)
will removes any enabling / disabling at the entity aspect level so now any 'Event.enable' calls at the EntityManager level, made either previously or in the future, will control notification.
Event.enable(“validationErrorsChanged”, myEntityManager, function(em) {
return em.customTag === “blue”;
})
will either enable or disable myEntityManager based on the current value of a ‘customTag’ property on myEntityManager. Note that this is dynamic, changing the customTag value will cause events to be enabled or disabled immediately.
isEnabled
-
eventName
-
target
Returns whether for a specific event and a specific object and its children, notification is enabled or disabled or not set.
Parameters:
-
eventName
StringThe name of the event.
-
target
ObjectThe object for which we want to know if notifications are enabled.
Returns:
A null is returned if this value has not been set.
Example:
Event.isEnabled(“propertyChanged”, myEntityManager)
publish
-
data
-
[publishAsync=false]
-
[errorCallback]
Publish data for this event.
Parameters:
-
data
ObjectData to publish
-
[publishAsync=false]
Boolean optionalWhether to publish asynchonously or not.
-
[errorCallback]
Function optionalWill be called for any errors that occur during publication. If omitted, errors will be eaten.
errorCallback([e])
-
[e]
Error optionalAny error encountered during publication execution.
-
Returns:
false if event is disabled; true otherwise.
Example:
// Assume 'salaryEvent' is previously constructed Event
salaryEvent.publish( { eventType: "payRaise", amount: 100 });
This event can also be published asychronously
salaryEvent.publish( { eventType: "payRaise", amount: 100 }, true);
And we can add a handler in case the subscriber 'mishandles' the event.
salaryEvent.publish( { eventType: "payRaise", amount: 100 }, true, function(error) {
// do something with the 'error' object
});
publishAsync
-
data
-
[errorCallback]
Publish data for this event asynchronously.
Parameters:
-
data
ObjectData to publish
-
[errorCallback]
Function optionalWill be called for any errors that occur during publication. If omitted, errors will be eaten.
errorCallback([e])
-
[e]
Error optionalAny error encountered during publication execution.
-
Example:
// Assume 'salaryEvent' is previously constructed Event
salaryEvent.publishAsync( { eventType: "payRaise", amount: 100 });
And we can add a handler in case the subscriber 'mishandles' the event.
salaryEvent.publishAsync( { eventType: "payRaise", amount: 100 }, function(error) {
// do something with the 'error' object
});
subscribe
-
[callback]
Subscribe to this event.
Parameters:
-
[callback]
Function optionalWill be called whenever 'data' is published for this event.
callback([data])
-
[data]
Object optionalWhatever 'data' was published. This should be documented on the specific event.
-
Returns:
This is a key for 'unsubscription'. It can be passed to the 'unsubscribe' method.
Example:
// Assume 'salaryEvent' is previously constructed Event
salaryEvent.subscribe(function (eventArgs) {
if (eventArgs.eventType === "payRaise") {
// do something
}
});
There are several built in Breeze events, such as EntityAspect.propertyChanged, EntityAspect.validationErrorsChanged as well.
// Assume order is a preexisting 'order' entity
order.entityAspect.propertyChanged.subscribe(function (pcEvent) {
if ( pcEvent.propertyName === "OrderDate") {
// do something
}
});
unsubscribe
-
unsubKey
Unsubscribe from this event.
Parameters:
-
unsubKey
NumberThe value returned from the 'subscribe' method may be used to unsubscribe here.
Returns:
Whether unsubscription occured. This will return false if already unsubscribed or if the key simply cannot be found.
Example:
// Assume order is a preexisting 'order' entity
var token = order.entityAspect.propertyChanged.subscribe(function (pcEvent) {
// do something
});
// sometime later
order.entityAspect.propertyChanged.unsubscribe(token);