Multi-Appointment Entity Scenario
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
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).
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
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
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.
property is used to specify the value of the key field in the table representing
For example the Appointments Collection Object -> EntryID field value stores the
key field (unique) value of the Appointment Record in the Appointments Table.
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.
In an MVVM scenario the collections on the dbiCalendarSL control are bound to
collections in the ViewModel via the Silverlight
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.
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
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.
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.
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.
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.