Data-Related Events

• Jan 23, 2019
• 4 minutes to read

This topic presents an overview of the Scheduler’s event model, describing the order in which events are raised.

Persistent objects publish two categories of data-related events.

The first set includes events that are raised before the action takes place. They are usually named with the “ing“ ending, and are used for pre-processing and cancelling the action. In this case, an event handler receives one object that has already been modified. If you set the Cancel parameter to true, the modification is rolled back.

Several events do not enable you to get the object in the unmodified state, so you will have to query the corresponding data object directly to obtain property values before modification.

Then, there are events in this category that receive both the original and the changed objects. For example, the SchedulerControl.AppointmentDrag event receives both the AppointmentDragEventArgs.EditedAppointment and AppointmentDragEventArgs.SourceAppointment objects. You should clearly distinguish these two objects when handling this event.

The second set of events includes events with the “ed“ ending, which are fired when the action has been performed. They provide notification and post-processing.

The two events that correspond to one action, and belong to different categories form an event pair. Events for AppointmentBaseCollection and ResourceBaseCollection collections, in contrast to single objects, do not come in pairs.

Guidelines for correct event handling are listed below:

• A good practice is to use PersistentObject.BeginUpdate/ PersistentObject.EndUpdate blocks, because it reduces the time required for initialization, and prevents raising events excessively. It is especially effective when event handling takes a considerable amount of time.
• Do not remove the object instance for which the first event in a pair is fired (the “ing” event). Its properties can be changed within the BeginUpdate / EndUpdate block. Deleting an object in the middle of this action, in between events, can result in some hard-to-find errors.
• Take special note of explicit SchedulerDataStorage.RefreshData calls. Data will be reloaded, and all custom field values that are not mapped will be lost. In particular, this may happen when a SchedulerDataStorage operates in unbound mode.
• When handling the SchedulerDataStorage.FetchAppointments event, change data in the data source at the Data layer. Do not modify data at the Storage layer, because the Storage automatically reloads its data from the Data layer’s data source when this event handler is executed.
• When the data source is changed, and the PersistentObjectStorage<T>.AutoReload property is set to true, the SchedulerDataStorage.AppointmentCollectionAutoReloading event occurs, and the Storage starts an automatic refresh. Use the SchedulerDataStorage.AppointmentCollectionAutoReloading event as a notification.

The order of events raised in typical situations is illustrated in the following table:

Action	Order in which events fire	Notes
Scheduler View initialization	SchedulerDataStorage.AppointmentCollectionAutoReloading, SchedulerDataStorage.AppointmentCollectionLoaded, SchedulerDataStorage.FetchAppointments, SchedulerDataStorage.FilterAppointment*
Visible interval modification of a View or a Control	SchedulerDataStorage.FetchAppointments, SchedulerDataStorage.FilterAppointment*
Clearing the PersistentObjectStorage	SchedulerDataStorage.AppointmentCollectionCleared
PersistentObjectStorage.DataSource substitution	SchedulerDataStorage.AppointmentCollectionLoaded
Adding a new appointment to a collection	SchedulerDataStorage.AppointmentInserting, SchedulerDataStorage.AppointmentsInserted, SchedulerDataStorage.FilterAppointment*
Occurrence appointments modification, resulting in exceptions for a particular recurrence pattern.	SchedulerDataStorage.AppointmentChanging, SchedulerDataStorage.AppointmentsInserted, SchedulerDataStorage.AppointmentsChanged, SchedulerDataStorage.FilterAppointment	The SchedulerDataStorage.AppointmentsInserted event is raised for the newly created AppointmentType.ChangedOccurrence.
Occurrence appointments removal, resulting in exceptions for a particular recurrence pattern.	SchedulerDataStorage.AppointmentDeleting, SchedulerDataStorage.AppointmentsInserted, SchedulerDataStorage.FilterAppointment*	The SchedulerDataStorage.AppointmentsInserted event is raised for the newly created AppointmentType.DeletedOccurrence.
Removing a pattern with two exceptions	SchedulerDataStorage.AppointmentDeleting, AppointmentDeleting, AppointmentDeleting, SchedulerDataStorage.AppointmentsDeleted, SchedulerDataStorage.FilterAppointment*	The SchedulerDataStorage.AppointmentDeleting event is first raised for the pattern and then - for all its exceptions. Note: if deleting of an exception is cancelled, the entire process is cancelled, and nothing is deleted.
Modification of three appointments at once with an action cancelled for one of them (e.g. drag-move)	SchedulerDataStorage.AppointmentChanging, AppointmentChanging, AppointmentChanging, SchedulerDataStorage.AppointmentsChanged	The SchedulerDataStorage.AppointmentChanging event is raised three times (one for each appointment). The action is cancelled in one of them. In the SchedulerDataStorage.AppointmentsChanged event, we have only two modified appointments.

* If the filter is applied, the SchedulerDataStorage.FilterAppointment event is raised for each appointment that falls within the visible interval.