Quickstart: Managing appointments
Collapse the table of content
Expand the table of content
Language: HTML | XAML

Quickstart: Managing appointments (HTML)

Through the Windows.ApplicationModel.Appointments namespace, you can create and manage appointments in a user's calendar app. Here, we'll show you how to create an appointment, add it to a calendar app, replace it in the calendar app, and remove it from the calendar app. We'll also show how to display a time span for a calendar app and create an appointment-recurrence object. Managing appointments is supported starting with Windows 8.1.

Here we reference the Appointments API sample. This sample demonstrates how to manage appointments through the API of the Windows.ApplicationModel.Appointments namespace from within Windows Runtime apps.

Prerequisites

  • We recommend that you be familiar with Microsoft Visual Studio and its associated templates.
  • We recommend that you be familiar with JavaScript development.

Create an appointment and apply data to it

Create a Windows.ApplicationModel.Appointments.Appointment object and assign it to a variable. Then, apply to the Appointment the appointment properties that were supplied through the UI by a user.


    function createAppointment() {
        var isAppointmentValid = true;
        var appointment = new Windows.ApplicationModel.Appointments.Appointment();

        // StartTime
        var startTime = document.querySelector('#startDatePicker').winControl.current;
        var time = document.querySelector('#startTimePicker').winControl.current;
        startTime.setMinutes(time.getMinutes());
        startTime.setHours(time.getHours());
        appointment.startTime = startTime;

        // Subject
        appointment.subject = document.querySelector('#subjectInput').value;

        if (appointment.subject.length > 255) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The subject cannot be greater than 255 characters.";
        }

        // Location
        appointment.location = document.querySelector('#locationInput').value;;

        if (appointment.location.length > 32768) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The location cannot be greater than 32,768 characters.";
        }

        // Details
        appointment.details = document.querySelector('#detailsInput').value;

        if (appointment.details.length > 1073741823) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The details cannot be greater than 1,073,741,823 characters.";
        }

        // Duration
        if (document.querySelector('#durationSelect').selectedIndex === 0) {
            // 30 minute duration is selected
            appointment.duration = (30 * 60 * 1000);
        } else {
            // 1 hour duration is selected
            appointment.duration = (60 * 60 * 1000);
        }

        // All Day
        appointment.allDay = (document.querySelector('#allDayCheckBox').checked);

        // Reminder
        if (document.querySelector('#reminderCheckBox').checked) {
            switch (document.querySelector('#reminderSelect').selectedIndex) {
                case 0:
                    appointment.reminder = (15 * 60 * 1000);
                    break;
                case 1:
                    appointment.reminder = (60 * 60 * 1000);
                    break;
                case 2:
                    appointment.reminder = (24 * 60 * 60 * 1000);
                    break;
            }
        }

        //Busy Status
        switch (document.querySelector('#busyStatusSelect').selectedIndex) {
            case 0:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.busy;
                break;
            case 1:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.tentative;
                break;
            case 2:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.free;
                break;
            case 3:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.outOfOffice;
                break;
            case 4:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.workingElsewhere;
                break;
        }

        // Sensitivity
        switch (document.querySelector('#sensitivitySelect').selectedIndex) {
            case 0:
                appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.public;
                break;
            case 1:
                appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.private;
                break;
        }

        // Uri
        var uriValue = document.querySelector('#uriInput').value;
        if (uriValue.length > 0) {
            try {
                appointment.uri = new Windows.Foundation.Uri(uriValue);
            }
            catch (e) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The Uri provided is invalid.";
            }
        }

        // Organizer
        // Note: Organizer can only be set if there are no invitees added to this appointment.
        if (document.querySelector('#organizerRadioButton').checked) {
            var organizer = new Windows.ApplicationModel.Appointments.AppointmentOrganizer();

            // Organizer Display Name
            organizer.displayName = document.querySelector('#organizerDisplayNameInput').value;

            if (organizer.displayName.length > 256) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The organizer display name cannot be greater than 256 characters.";
            } else {
                // Organizer Address (e.g. Email Address)
                organizer.address = document.querySelector('#organizerAddressInput').value;

                if (organizer.address.length > 321) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The organizer address cannot be greater than 321 characters.";
                } else if (organizer.address.length === 0) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The organizer address must be greater than 0 characters.";
                } else {
                    appointment.organizer = organizer;
                }
            }
        }

        // Invitees
        // Note: If the size of the Invitees list is not zero, then an Organizer cannot be set.
        if (document.querySelector('#inviteeRadioButton').checked) {
            var invitee = new Windows.ApplicationModel.Appointments.AppointmentInvitee();

            // Invitee Display Name
            invitee.displayName = document.querySelector('#inviteeDisplayNameInput').value;

            if (invitee.displayName.length > 256) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The invitee display name cannot be greater than 256 characters.";
            } else {
                // Invitee Address (e.g. Email Address)
                invitee.address = document.querySelector('#inviteAddressInput').value;

                if (invitee.address.length > 321) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The invitee address cannot be greater than 321 characters.";
                } else if (invitee.address.length === 0) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The invitee address must be greater than 0 characters.";
                } else {
                    // Invitee Role
                    switch (document.querySelector('#inviteeRoleSelect').selectedIndex) {
                        case 0:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.requiredAttendee;
                            break;
                        case 1:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.optionalAttendee;
                            break;
                        case 2:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.resource;
                            break;
                    }

                    // Invitee Response
                    switch (document.querySelector('#inviteeResponseSelect').selectedIndex) {
                        case 0:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.none;
                            break;
                        case 1:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.tentative;
                            break;
                        case 2:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.accepted;
                            break;
                        case 3:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.declined;
                            break;
                        case 4:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.unknown;
                            break;
                    }

                    appointment.invitees.append(invitee);
                }
            }
        }

        if (isAppointmentValid) {
            document.querySelector('#result').innerText = "The appointment was created successfully and is valid.";
        }
    }


Add an appointment to the user's calendar

Create a Windows.ApplicationModel.Appointments.Appointment object and assign it to a variable. Then, call the AppointmentManager.ShowAddAppointmentAsync(Appointment, Rect, Placement) method to show the default appointments provider add-appointment UI to enable the user to add an appointment. If the user clicked Add, the sample prints the appointment identifier that ShowAddAppointmentAsync returned.


    function addAppointment(e) {
        // Create an Appointment that should be added the user's appointments provider app.
        var appointment = new Windows.ApplicationModel.Appointments.Appointment();

        // Get the selection rect of the button pressed to add this appointment
        var boundingRect = e.srcElement.getBoundingClientRect();
        var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

        // ShowAddAppointmentAsync returns an appointment id if the appointment given was added to the user's calendar.
        // This value should be stored in app data and roamed so that the appointment can be replaced or removed in the future.
        // An empty string return value indicates that the user canceled the operation before the appointment was added.
        Windows.ApplicationModel.Appointments.AppointmentManager.showAddAppointmentAsync(appointment, selectionRect, Windows.UI.Popups.Placement.default)
            .done(function (appointmentId) {
                if (appointmentId) {
                    document.querySelector('#result').innerText = "Appointment Id: " + appointmentId;
                } else {
                    document.querySelector('#result').innerText = "Appointment not added";
                }
            });
    }


Replace an appointment in the user's calendar

Create a Windows.ApplicationModel.Appointments.Appointment object and assign it to a variable. Then, call the appropriate AppointmentManager.ShowReplaceAppointmentAsync method to show the default appointments provider replace-appointment UI to enable the user to replace an appointment. The user also provides the appointment identifier that they want to replace. This identifier was returned from AppointmentManager.ShowAddAppointmentAsync. If the user clicked Replace, the sample prints that it updated that appointment identifier.


    function replaceAppointment(e) {
        // The appointment id argument for ReplaceAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
        var appointmentIdOfAppointmentToReplace = document.querySelector('#appointmentIdInput').value;

        if (!appointmentIdOfAppointmentToReplace) {
            document.querySelector('#result').innerText = "The appointment id cannot be empty";
        } else {
            // The Appointment argument for ReplaceAppointmentAsync should contain all of the Appointment's properties including those that may have changed.
            var appointment = new Windows.ApplicationModel.Appointments.Appointment();

            // Get the selection rect of the button pressed to replace this appointment
            var boundingRect = e.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            // ReplaceAppointmentAsync returns an updated appointment id when the appointment was successfully replaced.
            // The updated id may or may not be the same as the original one retrieved from AddAppointmentAsync.
            // An optional instance start time can be provided to indicate that a specific instance on that date should be replaced
            // in the case of a recurring appointment.
            // If the appointment id returned is an empty string, that indicates that the appointment was not replaced.
            if (document.querySelector('#instanceStartDateCheckBox').checked) {
                // Replace a specific instance starting on the date provided.
                var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;

                Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
                     appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
                    .done(function (updatedAppointmentId) {
                        if (updatedAppointmentId) {
                            document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
                        } else {
                            document.querySelector('#result').innerText = "Appointment not replaced";
                        }
                    });
            } else {
                // Replace an appointment that occurs only once or in the case of a recurring appointment, replace the entire series.
                Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
                     appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default)
                    .done(function (updatedAppointmentId) {
                        if (updatedAppointmentId) {
                            document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
                        } else {
                            document.querySelector('#result').innerText = "Appointment not replaced";
                        }
                    });
            }
        }
    }


Remove an appointment from the user's calendar

Call the appropriate AppointmentManager.ShowRemoveAppointmentAsync method to show the default appointments provider remove-appointment UI to enable the user to remove an appointment. The user also provides the appointment identifier that they want to remove. This identifier was returned from AppointmentManager.ShowAddAppointmentAsync. If the user clicked Delete, the sample prints that it removed the appointment specified by that appointment identifier.


    function removeAppointment(e) {
        // The appointment id argument for ShowRemoveAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
        var appointmentId = document.querySelector('#appointmentIdInput').value;

        // The appointment id cannot be empty.
        if (!appointmentId) {
            document.querySelector('#result').innerText = "The appointment id cannot be empty";
        } else {
            // Get the selection rect of the button pressed to remove this appointment
            var boundingRect = e.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            // ShowRemoveAppointmentAsync returns a boolean indicating whether or not the appointment related to the appointment id given was removed.
            // An optional instance start time can be provided to indicate that a specific instance on that date should be removed
            // in the case of a recurring appointment.
            if (document.querySelector('#instanceStartDateCheckBox').checked) {
                // Remove a specific instance starting on the date provided.
                var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;

                Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
                     appointmentId, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
                    .done(function (removed) {
                        if (removed) {
                            document.querySelector('#result').innerText = "Appointment removed";
                        } else {
                            document.querySelector('#result').innerText = "Appointment not removed";
                        }
                    });
            } else {
                // Remove an appointment that occurs only once or in the case of a recurring appointment, remove the entire series.
                Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
                 appointmentId, selectionRect, Windows.UI.Popups.Placement.default)
                .done(function (removed) {
                    if (removed) {
                        document.querySelector('#result').innerText = "Appointment removed";
                    } else {
                        document.querySelector('#result').innerText = "Appointment not removed";
                    }
                });
            }
        }
    }


Show a time span for the appointments provider

Call the AppointmentManager.ShowTimeFrameAsync method to show a specific time span for the default appointments provider's primary UI if the user clicked Show. The sample prints that the default appointments provider appeared on screen.


    // Show the appointment provider app at the current date and time with a 1 hour duration
    function showTimeFrame() {
        var dateToShow = new Date();
        Windows.ApplicationModel.Appointments.AppointmentManager.showTimeFrameAsync(dateToShow, (60 * 60 * 1000))
            .done(function () {
                document.querySelector('#result').innerText = "The default appointments provider should have appeared on screen.";
            });
    }


Create an appointment-recurrence object and apply data to it

Create a Windows.ApplicationModel.Appointments.AppointmentRecurrence object and assign it to a variable. Then, apply to the AppointmentRecurrence the recurrence properties that were supplied through the UI by a user.


    function createRecurrence() {
        var isRecurrenceValid = true;
        var recurrence = new Windows.ApplicationModel.Appointments.AppointmentRecurrence();

        // Unit
        switch (document.querySelector('#unitSelect').selectedIndex) {
            case 0:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.daily;
                break;
            case 1:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly;
                break;
            case 2:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthly;
                break;
            case 3:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay;
                break;
            case 4:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearly;
                break;
            case 5:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay;
                break;
        }

        // Occurrences
        // Note: Occurrences and Until properties are mutually exclusive.
        if (document.querySelector('#occurrencesRadioButton').checked) {
            recurrence.occurrences = document.querySelector('#occurrencesRange').valueAsNumber;
        }

        // Until
        // Note: Until and Occurrences properties are mutually exclusive.
        if (document.querySelector('#untilRadioButton').checked) {
            recurrence.until = document.querySelector('#untilDatePicker').winControl.current;
        }

        // Interval
        recurrence.interval = document.querySelector('#intervalRange').valueAsNumber;

        // Week of the month
        switch (document.querySelector('#weekOfMonthSelect').selectedIndex) {
            case 0:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.first;
                break;
            case 1:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.second;
                break;
            case 2:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.third;
                break;
            case 3:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.fourth;
                break;
            case 4:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.last;
                break;
        }

        // Days of the Week
        // Note: For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values, at least one day must be specified.
        if (document.querySelector('#sundayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.sunday; }
        if (document.querySelector('#mondayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.monday; }
        if (document.querySelector('#tuesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.tuesday; }
        if (document.querySelector('#wednesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.wednesday; }
        if (document.querySelector('#thursdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.thursday; }
        if (document.querySelector('#fridayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.friday; }
        if (document.querySelector('#saturdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.saturday; }

        if (((recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly)       ||
             (recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay) ||
             (recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay)) &&
            (recurrence.daysOfWeek === Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.none)) {
            isRecurrenceValid = false;
            document.querySelector('#result').innerText = "The recurrence specified is invalid. For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values, 
                                                           at least one day must be specified.";
        }

        // Month of the year
        recurrence.month = document.querySelector('#monthOfYearRange').valueAsNumber;

        // Day of the month
        recurrence.day = document.querySelector('#dayOfMonthRange').valueAsNumber;

        if (isRecurrenceValid)
        {
            document.querySelector('#result').innerText = "The recurrence specified was created successfully and is valid.";
        }
    }


Summary and next steps

Now you have a basic understanding of how to manage appointments. Download the Appointments API sample from the code gallery to see the complete sample of how to manage appointments.

Related topics

Appointments API sample

 

 

Show:
© 2017 Microsoft