Multi-Appointment Entity Scenario

The data/object relationship that governs the binding of the dbiCalendarSL control to a database revolves around the Add/Edit/Delete of appointments including the effect of the actions on the relationships established between the appointment and multiple entities supported by the application.   For example an appointment scheduling application that allows the scheduling of an appointment such as a meeting in more than one location.  In this scenario any action other than the locations on the appointment is recorded in a single record in the database.  The Locations information for the appointment is recorded in an AppointmentLocations table that contains one record for each location the appointment is scheduled. 

Loading the control from a database

The dbiCalendarSL control object collections are designed to represent the tables in which the objects are persisted as data.  Accordingly the collections are loaded by reading in the associated tables.  Appointments represent the time period assigned to a Task or Tasks and/or or to a resource or group of resources such as a Location(s) and/or a Contact(s). 

Before adding appointments to the control, the developer should populate the Contacts, Tasks, and Locations collections with the data objects representing the data being scheduled in the calendar.  In addition to the standard properties used to describe the Appointment, Contact, Location, and Task entities there are two key properties on each collection object in the control used to bind the objects to the database; EntryID and Tag.   The dbiCalendarSL control defines a period of time over which collaboration data is presented.  The time period is defined by a start and end date.  As each record is processed from the database a new dbiCalendarSL object is created, its properties are set to reflect the record in the object, and then the object is stored in the appropriate collection in the control.   When the control is first instanced the start and end dates for the control are set.  These values then become the base parameters for selecting appointment records from the database to load in to the control.

To load the Appointments from the database the developer selects all appointments that match the criteria set on the dbiCalendarSL control (date range, Contacts, Locations, Tasks) and programmatically loops through the records creating a new dbiAppointmentItem object for each record.  If the data environment requires multiple Contacts, Locations, and/or Tasks (Multi-Appointment Entity Scenario), the developer is required to create one object in the appropriate appointment entity collection (Locations, Contacts, Tasks) and one object in the appointment Data entity collection (ContactsData, LocationsData, TasksData) placing the record describing the relationship in the tag property of the AppointmentData entity object.

EntryID Property

The EntryID property is used to specify the value of the key field in the table representing the entity.  For example the Appointments Collection Object -> EntryID field value stores the key field (unique) value of the Appointment Record in the Appointments Table.

Tag Property

The Tag property in the entity collection objects can be used to store any type of object however it is ideally suited to store the DataRow or similar object representing the record in the database that defines the entity.

Writing changes back to the database

Changes to an appointment are surfaced through events raised in the control at the time the user interacts with the dbiCalendarSL control or an appointment in the control; for example creating, moving, or selecting to delete an appointment.  The key to reflecting these changes is to create, or identify and modify the data object(s) related to the appointment being created or changed. 

To persist the relationship between a dbiCalendarSL object and the database object it represents store the database object in the dbiCalendarSL object's Tag property. Tags are of type Object and can therefore be used to store any kind of object, including an object from a database maintained in memory. If the data access for the application implements collections of objects used to represent the physical tables in a database, then storing the database object in the object's Tag property can be a very powerful tool for providing fast read/write/delete access to the data being represented by the object.

NOTE: In an MVVM scenario the collections on the dbiCalendarSL control are bound to collections in the ViewModel via the Silverlight {Binding= … technique.  For example:

Appointments="{Binding Path=vmAppointments,Mode=TwoWay}"

In this case the changes to the appointment are reflected in the collections in the ViewModel and updating of the database is carried out through events in the ViewModel. 

Adding an Appointment

When the user selects a time period in the control and begins typing the AfterAppointmentAdd event fires in the control.  The "e" argument passed in to the event includes the appointment object created by the control.  This allows the developer to create a new data object in the database to reflect the new appointment object and assign the new data object to the tag property of the new appointment object.  This new data object can then be written back to the physical table via the connection managing the physical data.

IMPORTANT NOTE:  If the appointment is created with the control's AppointmentType set to a value other than Date, i.e. Contact, Location, or Task, and/or if Grouping is turned on in the control, the appointment will be created with a defaulted value in the Contact, Location, or Task collection based upon the column values in which the appointment was created.  This requires the auto-created entry be reflected in the database at the time the appointment is created.  In a Single Appointment Entity Scenario, this requires the assigning of the entities EntryID to the appropriate column in the data object.  In a Multi-Appointment Entity Scenario, this requires a data object be created to reflect the addition of each of the appropriate entities (AppointmentType and GroupBy) to the appointment's entity collection(s).  For example if the control's AppointmentType is set to Contact and the GroupBy is set to Location, then when the user adds an appointment through the UI, the Contact and Location assigned to the column will be automatically added to the appointment's Contacts and Locations collections respectively.  The developer must then create a data object in the appropriate table in the database to reflect the Contact and Location being added to the appointment.  This data object is then assigned to the tag property of the AppointmentData object created to reflect the addition of the entity(s) to the appointment.

Editing (Changing) an Appointment

When the user selects to resize (change the start or end time) or move within a column or between columns, the control fires an AfterAppointmentChange event.  The "e" argument passed in to the event includes the Appointment object being moved.  This allows the developer to retrieve the data object stored in the tag property of the appointment to reflect the changes in the record of the table reflecting the state of the appointment object. 

IMPORTANT NOTE:  If the appointment is moved between columns and the control's columns are grouped in any way on Contact, Location, and/or Task then the control will automatically reflect changes to the appointment object's Contacts, Locations, and/or Tasks collections to reflect the move.  The developer must then test for changes in these collections and modify the Appointment's ContactsData, LocationsData, and/or TasksData collections and respective data objects stored in the tag property of the AppointmentData objects in the collections.

Deleting an Appointment

When the code is executed to delete an appointment the developer has access to the data object contained in the tag property of the appointment so it may be marked for deletion in the physical data. 

IMPORTANT NOTE:  In the case of a Multi-Appointment Entity Scenario, the developer must first delete the Appointment->Entity relationship(s) on the appointment before deleting the appointment itself.  The AppointmentData object representing a relationship between an appointment and an entity contains the data object to be deleted in its Tag property.

 SUMMARY

Databinding the dbiCalendarSL control requires three distinct points of integration; loading the data from the database, responding to changes (moves/edits) to the appointments in the calendar object, and responding to Adds (new) and Deletes to the appointments in the calendar object. Each of the objects in the calendar (appointments, contacts, tasks, and locations) has properties that allow the developer to persist the relationship of the object in the database being reflected.  Each event that is fired in the calendar passes the appointment against which the event occurred (move, size, add) to allow the developer to read the necessary property values (start time, end time, etc.) and its persistence scheme (record id, database object, etc.) to the object in the database.