Show:

Event Class

Module: core

Class to support basic event publication and subscription semantics.

Methods

<ctor> Event

(
  • name
  • publisher
  • [defaultErrorCallback]
)

Constructor for an Event

Parameters:

  • name String
  • publisher Object

    The object that will be doing the publication. i.e. the object to which this event is attached.

  • [defaultErrorCallback] Function optional

    If omitted then subscriber notification failures will be ignored.

    errorCallback([e])

    • [e] Error optional

      Any error encountered during subscription execution.

Example:

salaryEvent = new Event("salaryEvent", person);

enable

(
  • eventName
  • target
  • isEnabled
)
static

Enables or disables the named event for an object and all of its children.

Parameters:

  • eventName String

    The name of the event.

  • target Object

    The 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 | Function

    A 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
)
Boolean | Null static

Returns whether for a specific event and a specific object and its children, notification is enabled or disabled or not set.

Parameters:

  • eventName String

    The name of the event.

  • target Object

    The object for which we want to know if notifications are enabled.

Returns:

Boolean | Null:

A null is returned if this value has not been set.

Example:

Event.isEnabled(“propertyChanged”, myEntityManager)

publish

(
  • data
  • [publishAsync=false]
  • [errorCallback]
)
Boolean

Publish data for this event.

Parameters:

  • data Object

    Data to publish

  • [publishAsync=false] Boolean optional

    Whether to publish asynchonously or not.

  • [errorCallback] Function optional

    Will be called for any errors that occur during publication. If omitted, errors will be eaten.

    errorCallback([e])

    • [e] Error optional

      Any error encountered during publication execution.

Returns:

Boolean:

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 Object

    Data to publish

  • [errorCallback] Function optional

    Will be called for any errors that occur during publication. If omitted, errors will be eaten.

    errorCallback([e])

    • [e] Error optional

      Any 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]
)
Number

Subscribe to this event.

Parameters:

  • [callback] Function optional

    Will be called whenever 'data' is published for this event.

    callback([data])

    • [data] Object optional

      Whatever 'data' was published. This should be documented on the specific event.

Returns:

Number:

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
)
Boolean

Unsubscribe from this event.

Parameters:

  • unsubKey Number

    The value returned from the 'subscribe' method may be used to unsubscribe here.

Returns:

Boolean:

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);