Appointments

• Jul 18, 2024
• 7 minutes to read

Scheduler appointments are objects of the DxSchedulerAppointmentItem class. Appointments are stored in the DxSchedulerDataStorage object. They are automatically created from source objects retrieved from the AppointmentsSource collection. For additional information on data binding, refer to Bind to Data.

Appointment Types

The DevExpress Blazor Scheduler supports different appointment types: one-time, all-day, and recurring.

One-Time Appointment

A one-time appointment has its start and end, and does not belong to any recurring series. The DxSchedulerAppointmentItem.Type is OneTime.

A source object for the one-time appointment has the following properties:

One-Time Appointment

@code { 
  Appointment apt = new Appointment {
    AppointmentId = 1,
    Caption = "Website Redesign Plan",
    StartDate = DateTime.Today.Date + (new TimeSpan(1, 9, 30, 0)),
    EndDate = DateTime.Today.Date + (new TimeSpan(1, 11, 30, 0))
  };
}

All-Day Appointment

An all-day appointment is a one-time appointment that occupies the entire day or multiple days. Its Type is OneTime and the AllDay property is true.

All-day appointments are displayed in the all-day panel at the top of the view:

A user can turn on the All Day switch in the Appointment form to convert a one-time appointment to an all-day appointment.

An all-day appointment’s source object has the following properties:

All-Day Appointment

@code { 
  Appointment apt = new Appointment {
    AppointmentId = 2,
    Caption = "Customer Workshop",
    StartDate = date + (new TimeSpan(1, 12, 0, 0)),
    EndDate = date + (new TimeSpan(1, 13, 0, 0)),
    AllDay = true
  };
}

You can convert a one-time appointment to an all-day appointment. To do this, set the AllDay property to true. The Start and End property values still remain, but they are ignored. Only the Start property is used to determine the day that the all-day appointment occupies.

Recurring Appointments

A recurring appointment is an appointment that repeats on a schedule with a specified frequency: weekly, monthly, etc. You can create a pattern, a single record in your database that contains all the necessary information about the appointment (start time, end time, location, etc.). When the Blazor Scheduler is initialized, it automatically generates corresponding appointments (occurrences) based on the pattern.

Recurring appointments are indicated with a recurrence icon . Users can create, edit, and delete these appointments. Refer to Manage Recurring Appointments.

Run Demo: Scheduler - Recurring Appointments

There are 4 types of recurring appointments: pattern, occurrences, changed occurrence, and deleted occurrence.

Pattern

A base appointment that stores the rule according to which visible recurring appointments (occurrences) are generated. Patterns themselves are not visible and stored in the AppointmentsSource collection. Their Type is 1.

A pattern has the following properties:

Recurring Appointment

@code { 
    RecurringAppointment apt = new Appointment {
        AppointmentType = 1,
        Caption = "Meeting of Instructors",
        Label = 1,
        StartDate = date + (new TimeSpan(1, 10, 0, 0)),
        EndDate = date + (new TimeSpan(1, 10, 45, 0)),
        Recurrence = string.Format("<RecurrenceInfo Start=\"{0}\" End=\"{1}\" WeekDays=\"62\" Id=\"6de79b21-6b16-4dea-9736-c500058ec858\" OccurrenceCount=\"25\" Range=\"1\" Type=\"1\" />", 
        ToString(date + (new TimeSpan(1, 10, 0, 0))), ToString(date + (new TimeSpan(1, 10, 45, 0)))),
        ResourceId = 1
    },
}

Occurrences

A series of visible appointments that are created from the pattern at runtime. These appointments are not kept in the AppointmentsSource collection. The appointments’ Start and End values are calculated based on a recurrence rule.

Changed Occurrence

When a user changes a recurring appointment in the UI, an exception appointment is created in the AppointmentsSource collection. This appointment has the ChangedOccurrence type and the IsException property set to true. The changed and regular occurrences have the same RecurrenceInfoId.

Changed occurrences are marked with a crossed-out occurrence icon.

A changed occurrence’s recurrence rule should look like this:

"<RecurrenceInfo Id=\"6de79b21-6b16-4dea-9736-c500058ec858\" Index=\"25\"/>"

Deleted Occurrence

When a user deletes a recurring appointment from the UI, an exception appointment is created in the AppointmentsSource collection. This appointment has the DeletedOccurrence type and the IsException property set to true. The deleted and regular occurrences have the same RecurrenceInfoId.

A deleted occurrence’s recurrence rule should look like this:

"<RecurrenceInfo Id=\"6de79b21-6b16-4dea-9736-c500058ec858\" Index=\"25\"/>"

Manage Appointments

Users can create, edit, select, and delete appointments in the UI or in code.

Create Appointment

1. Click an empty cell in the view and drag the mouse pointer across other cells to extend the selection.

2. Release the button. The compact edit form appears.

   

3. Fill in the fields and click Save or click the Expand Arrows button to show the pop-up (detailed) form:

   

4. Fill in the fields and click Save.

You can prevent users from creating new appointments. To do this, set the AllowCreateAppointment property to false.

Edit Appointment

Users can change an appointment as follows:

• Reschedule: drag and drop an appointment to another cell.
• Extend or shorten: drag the top or bottom appointment’s border.
• Change the appointment details.
• Change a resource: drag an appointment between resource groups.

To change the appointment details, follow the steps below:

1. Click an appointment to show its tooltip:

   

2. Click the Edit button to invoke the compact edit form.

   

3. Edit the fields and click Save.

   You can also use the pop-up (detailed) form to edit the appointment fields. To show the form, click the Expand Arrows button .

You can prevent users from editing appointments. To do this, set the AllowEditAppointment property to false.

Delete Appointment

1. Click an appointment to show its tooltip.

   

2. Click the Delete button .

Tip

If an appointment is a regular occurrence in a recurring series, a confirmation dialog appears as described in the Delete Recurring Appointment or Series section.

You can prevent users from deleting appointments. To do this, set the AllowDeleteAppointment property to false.

Manage Recurring Appointments

Create Recurring Series

Select a value other than Never in the Appointment form’s Repeat section to create a recurring appointment series from a one-time or all-day appointment:

The Recurrence form appears. It has a different layout for each rule type. Fill in the fields to specify the recurrence rule and click Save to assign it to the RecurrenceInfo property.

Edit Recurring Series

To edit a recurring appointment, click it to show its tooltip and click the Edit button. The following dialog appears:

• Click Edit series to invoke the Appointment form that allows you to modify the recurrence pattern and its recurrence rule. Click Save to save changes to the pattern and the DxSchedulerRecurrenceInfo property.
• Click Edit appointment to invoke the Appointment form without the Repeat section. This form prevents you from changing the recurrence rule. When you click Save, the AppointmentInserted method is called and a new Changed Occurrence) appointment is created. The appointment is stored in the AppointmentsSource collection.

Delete Recurring Appointment or Series

Click the recurring appointment to show the appointment tooltip and click the Delete button. The following dialog appears:

• Click Delete series to delete the recurrence pattern and all appointments that belong to a series, including changed occurrences.
• Click Delete appointment to remove the regular appointment occurrence and create a new hidden appointment that has the deleted occurrence type. The appointment is stored in the AppointmentsSource collection.

Restore Occurrence

If you edited a recurring appointment, you can revert the changed occurrence to a regular occurrence. For this, click the desired appointment to show the appointment’s tooltip and click the Restore Occurrence button .

Manage Appointments in Code

You can also manage appointments in code:

Operation	Methods/Properties	Events
Create appointments	CreateAppointmentItem(Boolean) CreateAppointmentAsync(DateTime, DateTime, Boolean, Object) SaveAppointmentAsync(DxSchedulerAppointmentItem)	AppointmentCreated AppointmentCreating AppointmentInserted AppointmentInserting
Get and edit appointments	GetAppointmentItemById(Object)	AppointmentUpdated AppointmentUpdating
Select appointments	SelectedAppointment	SelectedAppointmentChanged
Remove appointments	RemoveAppointment(DxSchedulerAppointmentItem) DeleteAppointmentAsync(DxSchedulerAppointmentItem)	AppointmentRemoved AppointmentRemoving

Use these events to implement CRUD operations in the Scheduler. Refer to the following topic for more information: Bind Blazor Scheduler to Data.

You can also restrict end-user operations that modify appointments. Refer to Restrict/Limit User Actions and Customize User Actions.

Appointment Snap Modes

For Month, Day, and Timeline views, you can specify how appointments snap to time cells. Use the SnapToCellsMode property of the corresponding view.

In the following image, the SnapToCellsMode property is set to Never:

In the image below, the SnapToCellsMode property is set to Always:

In the last image, the SnapToCellsMode property is set to Auto:

The following code snippet applies the SnapToCellsMode property to the Timeline view:

<DxScheduler StartDate="@DateTime.Today"
             DataStorage="@DataStorage">
    <DxSchedulerTimelineView SnapToCellsMode="SchedulerSnapToCellsMode.Always"
                             Duration="@(TimeSpan.FromHours(24))"
                             CellMinWidth="100">
        <Scales>
            <DxSchedulerTimeScale Unit="@SchedulerTimeScaleUnit.Day" UnitCount="1"></DxSchedulerTimeScale>
            <DxSchedulerTimeScale Unit="@SchedulerTimeScaleUnit.Hour" UnitCount="4"></DxSchedulerTimeScale>
        </Scales>
    </DxSchedulerTimelineView>
</DxScheduler>

@code {
    DxSchedulerDataStorage DataStorage = new DxSchedulerDataStorage()
    {
        AppointmentsSource = GetAppointments(),
        AppointmentMappings = new DxSchedulerAppointmentMappings()
        {
            Type = "AppointmentType",
            Start = "StartDate",
            End = "EndDate",
            Subject = "Caption",
            AllDay = "AllDay",
            Location = "Location",
            Description = "Description",
            LabelId = "Label",
            StatusId = "Status",
            RecurrenceInfo = "Recurrence"
        }
    };
    @* ... *@
}