JayData.org

JayData event handlers

Author: Robert Bonay June 16th, 2013


This document supposed to explain all the capabilities of JayData related to event handlers. All the statements are valid in the entire JayData ecosystam (JayData library, JayData Server, JayData Server Pro).

JayData provides a rich set of tools to build application logic around data-related events and implement triggers easily, just as site builders manage event handlers of DOM elements.

To understand the events, we will take a simplified Northwind data scheme as example and demonstrate with the Products and Categories tables, so let’s start with the definition of these entity types and the data context for JayData.

Using the snippet above JayData persists a new category to our in-browser WebSQL database. We will add events to this fist version of the code in the following sections.

Developers can define event handlers on four different levels:

  • EntityContext – If we define the event handlers on the EntityContext level, our event handler will be called every time we CRUD any instances of any types in any EntitySets.
  • EntitySet – We can assign event handlers to the Products EntitySet, in this case only CRUD actions to the Product EntitySet will call the event handlers.
  • Entity Type – Declaring an event handler on the Product type, actions will call it while CRUD-ing the Products or the OldProduct EntitySet.
  • Entity Instance – Yes, event handlers can be assigned even to a single entity instance.

 

EntityContext

EntitySet

Entity Type

Entity instance

Cancellable

No

Yes (before events)

Yes (before events)

No

Allows entity modifications

No

Only changed fields

Yes

No

Multiple event subscribers

Yes

No

Yes

Yes

EntityContext-level events

Available events:

  • ‘added’
  • ‘updated’
  • ‘deleted’

All these events are raised after the underlying actions.

Subscribing to the events

Unsubscribing from events

Remarks:

  • You can add multiple event subscribers with the same type, all of them will be fired
  • Event handlers does not get all the fields of the entity
  • added event handler get the fields set before + default values + new id
  • updated event handler get the changed properties
  • deleted event handler get only the Id in the itemData.data.Id property

EntitySet-level events

Available events:

  • beforeCreate / afterCreate
  • beforeRead / afterRead
  • beforeUpdate / afterUpdate
  • beforeDelete / afterDelete

Subscribing to the event:

Remarks:

  • Event handlers get an array of items, if you CRUD only a single entity, it will be in the first element of the array
  • Event handlers does not get all the fields of the entity
  • beforeCreate and afterCreate events get only the fields set to the new entity
  • beforeRead and afterRead events get the underlying EntitySet and the query
  • beforeUpdate and afterUpdate events get the changed properties
  • beforeDelete and afterDelete events get the Id of the entity

Cancelling the events

Synchronous cancellation:

Asynchronous cancellation:

Entity type-level events

Available events:

  • beforeCreate / afterCreate
  • beforeUpdate / afterUpdate
  • beforeDelete / afterDelete

Subscribing to the event:

Unsubscribing from the event:

Cancelling the event

Remarks:

    • You can add multiple event subscribers with the same type, all of them will be fired
    • Event handlers does not get all the fields of the entity

      • beforeCreate and afterCreate events get only the fields set to the new entity beforeUpdate and afterUpdate events get the changed properties
      • beforeDelete and afterDelete events get the Id of the entity

Entity instance-level events

JayData lets you to track all changes of object properties.

Available events

  • propertyChanging
  • propertyChanged
  • propertyValidationError

Subscribing to the events

Unsubscribing from the event

Remarks:

  • You can add multiple event subscribers with the same type, all of them will be fired. Yo can achive this by multiple attach() instructions.
  • You event hander will get the eventData, which contains the _propertyName, _oldValue and _newValue properties.

General behaviors

Using the context to query the database

All event handlers has got access to the database through the this keyword, which returns the current context. It’s recommended to set the value of the this to a new variable (we use self).

Did you like this article? Do you want to try these event handlers in action? Download the latest version JayData library or check out JayData server for node.js.