What Is an Appointment
- 5 minutes to read
This document introduces the Appointment concept, and describes the types of appointments, and their interaction with the Appointment Storage.
Appointment Overview
An appointment represents a scheduled time interval, and an end-user’s plans for this time interval. A plan could contain the appointment’s subject, location, different marks (status and labels), comments and any other custom properties.
A single appointment is an object that exposes the Appointment interface. The appointment’s appearance depends upon the active view (ASPxScheduler.ActiveView) which is used to show the Scheduler’s data. For instance, for the Day View a common appointment usually looks as shown in the image below.
All of a scheduler’s appointments are stored in the AppointmentStorage (which is a part of the Scheduler Storage and is accessed via its SchedulerStorage.Appointments property). The collection of all the appointments is accessed via the AppointmentStorageBase.Items property.
Also note that the Appointment Storage allows appointments data to be persisted in a datasource, and appointments assigned to particular resources. See the Scheduler Storage and Assigning Appointments to Resources topics, to learn more on how to do this.
Types of Appointments
Every appointment is of a particular type, which can be accessed via its Appointment.Type property. For example, a simple non-recurring appointment’s type is AppointmentType.Normal. All appointment types are listed by the AppointmentType enumeration’s members.
The following diagram illustrates the difference between the recurring and non-recurring appointment types.
To learn more about recurring appointments and the differences in their types, see the Recurring Appointments and Exceptions help document.
Appointment Categories
Appointments can be identified with Appointment Labels and Statuses. To extend appointment classification and enable tracking by different criteria, use custom fields. To start using them, review the How to: Create Appointments with Custom Fields document.
Creating Appointments
Appointments can be created by the end-user via keyboard or mouse input, as described in the Create an Appointment topic. The actions available to the user can be restricted by specifying the ASPxScheduler.OptionsCustomization property.
In code, you can create an appointment using a class constructor, the ASPxScheduler.CreateAppointment and related methods. You are advised not to use a simple constructor, because it doesn’t take into account custom fields, and you are required to add them manually. Then, a newly created appointment should be added to the SchedulerStorage using the AppointmentStorageBase.Add method of the appointment storage, available via the ASPxSchedulerStorage.Appointments property.
To specify default appointment properties which should be applied to all newly created appointments, handle the ASPxScheduler.InitNewAppointment event.
The client-side method clientScheduler.RaiseCallback(“MNUVIEW|NewAppointment”) can be used to invoke an appointment editing form for the new appointment.
The SchedulerStorageBase.CreateAppointment method creates an appointment with default attribute settings and custom fields. You should specify them via code, and add an appointment to the SchedulerStorage.
Modifying Appointments
End-users can modify the appointments as described in the Edit an Appointment topic.
End-users capabilities for appointment modifications can be restricted by specifying the corresponding properties of the ASPxScheduler.OptionsCustomization class.
To control the changes applied to the appointment, you should use the ASPxSchedulerDataWebControlBase.AppointmentChanging event, which is fired before the changed appointment is saved to the storage, and the ASPxSchedulerDataWebControlBase.AppointmentsChanged and ASPxSchedulerDataWebControlBase.AppointmentsInserted events, raised after modifications are applied.
To invoke the appointment editing form, you can use the client-side methods ASPxClientScheduler.ShowAppointmentFormByClientId and ASPxClientScheduler.ShowAppointmentFormByServerId. The command executed by the clientScheduler.RaiseCallback(“MNUAPT|OpenAppointment”) call invokes the editing form for the currently selected appointment.
An appointment’s attributes can be changed using the Appointment properties. Custom properties are accessible via the PersistentObject.CustomFields property using index notation.
To change the data record in the underlying data source which corresponds to the Appointment object, use the IPersistentObject.GetSourceObject method. An explicit cast is required for the returned object (e.g. to the DataRowView or XPBaseObject).
Selected appointments are contained within the ASPxScheduler.SelectedAppointments collection. To track the selection changes, you can subscribe to the ASPxClientScheduler.AppointmentsSelectionChanged client-side event.
Deleting Appointments
End-users can delete appointments as described in the Delete an Appointment document. Note that non-recurring appointments are deleted without confirmation, so you should handle the ASPxSchedulerDataWebControlBase.AppointmentDeleting event to prevent accidental deletion.
To delete an appointment in code, use the IPersistentObject.Delete method.
Before the actual deletion is accomplished, the ASPxSchedulerDataWebControlBase.AppointmentDeleting event is raised for each object being deleted. You can handle the event to decide about a specific appointment. After an appointment is deleted, the ASPxSchedulerDataWebControlBase.AppointmentsDeleted event occurs.
Displaying Appointments
You can change the text displayed within the appointment via the ASPxScheduler.InitAppointmentDisplayText event, and images via the ASPxScheduler.InitAppointmentImages event. The ASPxScheduler.AppointmentViewInfoCustomizing event enables you to modify the appointment’s style elements.
You can modify the appointment look via the template mechanism. For more information, review the Templates topic.
User Restrictions
You can restrict certain appointment operations via the set of properties and events named AllowAppointment*, such as SchedulerOptionsCustomization.AllowAppointmentDelete and ASPxScheduler.AllowAppointmentDelete. The corresponding event is fired only if the corresponding method is set to UsedAppointmentType.Custom. For more information, review the How to: Prevent End-Users from Editing Appointments.