| Binding the
dbiCalendarWPF control to a database |
| |
| The dbiCalendarWPF control encapsulates
collections, methods, events, and properties that
allow developers to bind the control to virtually
any data source containing collaborative data, such
as; appointments, contacts, locations, and tasks. At
its heart, dbiCalendarWPF presents appointment
information and provides a platform for end users to
visually interact with that information.
dbiCalendarWPF manages 5 collections internally:
|
| |
- Appointments
- Contacts
- Locations
- Tasks
- Custom Areas
|
| |
 |
| |
| It is important to note that the Appointment
Object encapsulates its own collections for
Contacts, Locations, and Tasks, allowing for 0, 1,
or many of any or all of those entities to be
associated with an appointment. In other words, one
appointment can be related to any number of
Contacts, Locations, and/or Tasks. The "Data"
collections on the Appointment Object are used to
store the Data Objects that represent the database
records for each Appointment -> Entity (Contact,
Location, Task) relationship. |
| |
There are two scenarios to consider when binding
the dbiCalendarWPF control to a database … the
simple or single appointment entity scenario and the
more complex multi-appointment entity scenario where
the appointment entities refer to multiple
locations, contacts, and/or tasks per appointment.
|
| |
| |
| Single Appointment
Entity Scenario |
| The data/object relationship that governs the
binding of the dbiCalendarWPF control to a database
revolves around the Add/Edit/Delete of appointments
without the need for consideration of managing the
one to many relationship between an appointment and
its multiple Locations, Contacts, and/or Tasks. In
this scenario any action on the appointment is
recorded in a single record in the database and is
reflected through the data object (DataRow) stored
in the tag property of the dbiCalendarWPF->Appointment
Object. |
| |
| |
 |
| |
| |
| Multi-Appointment
Entity Scenario |
The data/object relationship that governs the
binding of the
dbiCalendarWPF 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 and is reflected through the data object (DataRow)
stored in the tag property of the dbiCalendarWPF->Appointment
Object. The Locations information for the
appointment is recorded in an AppointmentLocations
table that contains one record for each location the
appointment is scheduled. The record (DataRow) for
each AppointmentLocation entry in the database is
stored in the Tag of an AppointmentData object in
the dbiCalendarWPF Appointment's LocationData object
collection.
|
|
 |
| |
| IMPORTANT
NOTE: For an example of binding the
dbiCalendarWPF control to a database please review
the dbiCalendarWPFDatabindingDemo application and
source code in the Product Manager -> Demos section. |
| |
| |
| Loading the control
from a database |
| The dbiCalendarWPF 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 the ADO.NET architecture, table records
(rows) are represented in memory by the DataRow
object. 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 dbiCalendarWPF 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
dbiCalendarWPF 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
dbiCalendarWPF 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 (Mult-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
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 dbiCalendarWPF control or an
appointment in the control; for example creating,
moving, using the built-in context menus, 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. This is
achieved by storing the DataRow associated with the
appointment object in the tag property of the
appointment object in the
dbiCalendarWPF control. If
the data environment requires multiple Contacts,
Locations, and/or Tasks per Appointment the DataRow
defining the relationship between the appointment
and the entity is stored in the Appointment/Data
collection (ContactsData, LocationsData, or
TasksData) object's tag property. The presence of
the DataRow allows the developer to reflect changes
to the data at the time the changes occur to the
appointment. |
| |
| |
| 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 DataRow to reflect the new appointment
object in the database and assign the new DataRow to
the tag property of the new appointment object. This
new DataRow can then be written back to the physical
table via the DataSet managing the DataRow. |
| |
| |
| 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
DataRow. In a Multi-Appointment Entity Scenario,
this requires a DataRow 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 DataRow/Record in the appropriate table in
the database to reflect the Contact and Location
being added to the appointment. This DataRow 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 (DataRow) 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 (DataRows)
stored in the tag property of the AppointmentData
objects in the collections. |
| |
| |
| Deleting an
Appointment |
| When the user elects to delete an appointment
via the built-in context menus the
AfterAppointmentContextMenuChange event is fired in
the control. The e.WasDeleted flag will be set to
true to indicate that the user selected Delete
Appointment from the menu. The Appointment Object in
the control is passed in to the event in the
e.Appointment argument, and from this the developer
has access to the data object contained in the tag
property of the appointment so it may be marked for
deletion. |
| |
| |
| 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. |
| |
| For additional helpful how
to hints see the Developing With... topic
items in the associated component help file. |
|
|
| |
| |
 |
| |
| |