Appointments

The Scheduler widget is designed to work with appointments - tasks, events and other similar data that should be scheduled in a timetable. Appointments can have different details, but the main details that allow appointments to be scheduled are the following.

  • text
    This is a key information about an appointment.

  • startDate
    The time (year/month/day/time) when an appointment start is scheduled.

  • endDate
    The time (year/month/day/time) when an appointment end is scheduled.

These are the fields that must be exposed by the objects defining appointment for the Scheduler widget.

JavaScript
var appointments = [
    {text: 'Meet with a customer', startDate: new Date(2015, 4, 10, 11, 0), endDate: new Date(2015, 4, 10, 13, 0)},
    {text: 'Discuss results', startDate: new Date(2015, 5, 11, 12, 0), endDate: new Date(2015, 4, 11, 13, 0)}
]
NOTE
There can be more fields used to define an appointment. For details, refer to the Default Item Template Reference section.

To assign appointments to the Scheduler widget, use the widget's dataSource option.

JavaScript
var schedulerOptions = {
    dataSource: appointments
}

The widget displays the assigned appointments as rectangles laying on the timetable of the scheduler area. The time cells it occupies correspond to its specified time interval.

Scheduler Appointment

Note that if the appointment width is less than 40 pixels or its height is less than 15 pixels, the appointment subject, end and start dates are hidden. If you want to disable this behavior, override the ".dx-scheduler-appointment-empty .dx-scheduler-appointment-content" CSS.

CSS
.dx-scheduler-appointment-empty .dx-scheduler-appointment-content {
    display: block;
}

You can customize an appointment appearance. To learn more about Appointments as the widget's visual elements, refer to the Visual Elements | Appointment topic.

In this article, you will learn what possibilities are provided for adding, modifying and deleting appointments, and how to organize a data source for the widget so that all these operations are easily performed.

Provide a Data Source

As all DevExtreme widgets that deal with data, the Scheduler widget works with the DataSource object from the DevExtreme Data Library. The DataSource connects the widget with data provided by a web service or data stored locally. The DataSource is a stateful object that keeps sorting, grouping, filtering, and keeps data transformation options and applies them each time data is loaded. The DataSource's underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. You can use one of the ready-to-use Stores - the ArrayStore to work with in-memory data, LocalStore to work with data from a local storage or ODataStore to work with an OData service - as well as the CustomStore to realize the Store interface and organize work with a custom service. No matter which Store you specify for the scheduler's data source object, all data modification operations will be performed using the unified Store interface.

Here is an example of the DataSource object that uses an ODataStore to operate with data provided by an OData service.

JavaScript
var schedulerDataSource = new DevExpress.data.DataSource({
    store: {
        type: 'odata',
        url: 'http://url/to/the/source'
    },
    paginate: false
});

The dataSource option takes on the DataSource object or its configuration object.

JavaScript
var schedulerOptions = {
    dataSource: schedulerDataSource
}

To learn more about the DataSource object and Stores, refer to the Data Layer article.

Custom Store Implementation Specifics

When you have a custom web service with its own data accessing logic, use a CustomStore to operate data. This type of store requires the implementation of a function for each data access operation. When implementing the load function, apply the widget's filter to the query result.

JavaScript
var schdulerOptions = {
    dataSource: new DevExpress.data.DataSource({
        store: new DevExpress.data.CustomStore({
            load: function(options) {
                var result = $.Deferred();
                $.ajax({
                    url: "/...",
                    data: {
                        start: schedulerInstance.getStartViewDate().getTime(),
                        end: schedulerInstance.getEndViewDate().getTime(),
                        ownerid: schedulerInstance.option("resources")
                    }
                }).done(function(response){
                    result.resolve(response);
                });
                return result.promise();
            },
            //...
        }),
        //...
    }),
    //...
}
See Also

Note that the function passed to the load option should support the Scheduler field in addition to the standard field set of the argument object. This field holds an object containing the following fields.

  • startDate
    Specifies the start date of a range of appointments to be loaded.

  • endDate
    Specifies the end date of a range of appointments to be loaded.

  • resources
    Specifies resources used to filter the appointments to be loaded.

View Demo

Add Appointments

Appointments can be added by end users in the UI and programmatically in code.

Add Appointments in UI

To add an appointment, do the following.

  • Click a cell in the scheduler timetable. The cell will be focused and ready to be used for creating an appointment.

  • Click the focused cell. A popup window will be invoked.

  • In the popup window, specify appointment details and click Done. This will create an appointment and add it to the bound data source.

NOTE
By default, when you are working with an appointment using a UI, the fields displaying start date and end date timezones are not available. To show them, you can add the following code to the scheduler's options.
JavaScript
var schedulerOptions = {
    . . . 
    onAppointmentFormCreated: function(arg) {
        var form = arg.form;
        form.itemOption("startDateTimeZone", { visible: true });
        form.itemOption("endDateTimeZone", { visible: true });
    }
}

Add Appointments in Code

To add an appointment in code, use the widget's addAppointment(appointment) method passing the appointment object as a parameter. This method adds the appointment to the bound data source.

In addition, you can handle the appoinmentAdding and appointmnetAdded events raised before and after you add an appointment to the data source.

Modify Appointments

Appointments can be modified by end users in the UI and programmatically in code.

Modify Appointments in UI

You can modify an appointment using one of the following techniques.

  • To change an appointment's start and end date/time, move the appointment by dragging it to another place within the scheduler view.

  • To change an appointment's start or end time, stretch or tighten the appointment by dragging its top/bottom border within the scheduler timetable column.

  • To change appointment details, click the appointment and then click the Open appointment button. In the invoked popup window, apply the required modifications.

All the modifications are saved to the bound data source.

NOTE
By default, when you are working with an appointment using a UI, the fields displaying start date and end date timezones are not available. To show them, you can add the following code to the scheduler's options.
JavaScript
var schedulerOptions = {
    . . .
    onAppointmentFormCreated: function(arg) {
        var form = arg.form;
        form.itemOption("startDateTimeZone", { visible: true });
        form.itemOption("endDateTimeZone", { visible: true });
    }
}
NOTE
When you are modifying a recurring appointment using a UI, the Scheduler prompts you to edit only the active appointment or the entire series.

By default, if you are modifying a recurring appointment using a UI, the widget displays a dialog that prompts you to edit only the active appointment or the entire series. To change this behavior, assign the required value to the recurrenceEditMode option. The option accepts the following values.

  • dialog
    Displays a dialog that suggests to a user to choose between editing an entire series or only the current appointment.
  • series
    Enables an end-user to edit only the entire appointment series.
  • occurrence
    Enables an end-user to edit only the current appointment.

Modify Appointments in Code

To modify an appointment in code, use the widget's updateAppointment(target, appointment) method passing the appointment object to be updated and an updated appointment object as parameters. This method updates the appointment in the bound data source.

In addition, you can handle the appointmentUpdating and appointmnetUpdated events raised before and after you insert an updated appointment to the data source.

Customize Appointment Details Form

To customize an appointment details form, do the following.

  • Create the onAppointmentFormCreated handler to obtain the Form instance, used to render the appointment details.

    JavaScript
    var schedulerOptions = {
        ...
        onAppointmentFormCreated: function (e) {
            var form = e.form;
        }
    };
  • Use the itemOption method to update form item options.

    JavaScript
    var schedulerOptions = {
        ...
        onAppointmentFormCreated: function (e) {
            var form = e.form;
            form.itemOption("startDate", {
                helpText: "Select a date between May 11 and 27",
                editorOptions: {
                    min: new Date(2016, 4, 11),
                    max: new Date(2016, 4, 27),
                    type: 'datetime'
                }
            });
        }
    };

Watch Video

Delete Appointments

Appointments can be deleted by end users in the UI and programmatically in code.

Delete Appointments in UI

To delete an appointment, click the appointment and then click the basket icon in the invoked tooltip.

The appointment will be deleted from the bound data source.

Delete Appointments in Code

To delete an appointment in code, use the widget's deleteAppointment(appointment) method passing the appointment object to be deleted. This method deletes the appointment from the bound data source.

In addition, you can handle the appoinmentDeleting and appointmnetDeleted events raised before and after you delete an appointment from the data source.

NOTE
When you are deleting a recurring appointment using a UI, the Scheduler prompts you to edit either the active appointment or the entire series.