Recurrences on the Client

Schedule items can recur in time, following a specific recurrence pattern. For example an event could be set to occur each Monday, on the third day of each month, and so on. Associate a Recurrence object with an Item instance to specify the time period, pattern, and other properties for the repetition of that item in time.

Once a recurrent item is created in a Calendar instance, the calendar creates multiple occurrences of the item in the time period being visualized. Occasionally you will get references to these occurrences passed as arguments to the calendar events or returned by the calendar methods. Occurrences are instances of the same class as of the item that was set recurrent, however their recurrence state is set to Occurrence - visible through the item's getRecurrenceState method. If a user moves a recurrent event's occurrence in the calendar, thus changing its start or end time, or changes the occurrence text, an exception is created. RecurrenceExceptions contain data about these item instances whose recurrence state is set to Exception.

Creating recurrent patterns on the client

In order to programmatically create a recurrent pattern on the client, a Recurrence object must be created and then create a new or choose an already existing Item as its Master item. To create a new Recurrence instance, a special Object, containing information about the values of its properties must be passed as argument to the Recurrence constructor.

This is a complete table of the names of the recurrence's properties, which can be set programmatically from the client side:

Name	Value type	Description
pattern	RecurrencePattern	Specifies the interval at which recurring events occur.
dailyRecurrence	DailyRecurrence	Specifies the type of daily occurrence pattern, when pattern is set to Daily.
monthlyRecurrence	MonthlyRecurrence	Specifies the type of monthly occurrence pattern, when pattern is set to Monthly.
yearlyRecurrence	YearlyRecurrence	Specifies the type of yearly occurrence pattern, when pattern is set to Yearly.
days	Number	Specifies the number of days between two consecutive occurrences of the same event. Used when pattern is set to Daily.
weeks	Number	Specifies the number of weeks between two consecutive occurrences of the event. Used when pattern is set to Weekly.
daysOfWeek	DaysOfWeek	Specifies the days of the week when the event occurs. Used when pattern is set to Weekly.
dayOfMonth	Number	Specifies the day of the month when the event occurs. Used when pattern is set to Monthly or Yearly.
months	Number	Specifies the number of months between two consecutive occurrences of the same event. Used when pattern is set to Monthly.
occurrence	Occurrence	Specifies on which occurrence of the week within the month the event occurs. Used when pattern is set to Monthly or Yearly and the monthlyRecurrence or yearlyRecurrence properties are set to ByDayType or ByDayType.
day	DayOfWeekType	Specifies the day of the week when the event occurs. Used when pattern is set to Monthly or Yearly and the monthlyRecurrence or yearlyRecurrence properties are set to ByDayType or ByDayType.
monthOfYear	Number	Specifies the month of the year when the event occurs. Used when pattern is set to Yearly.
interval	Number	Specifies the number of hours between two consecutive occurrences of the same event. Used when pattern is set to ByTimeInterval.
recurrenceEnd	RecurrenceEnd	Specifies when to stop repeating the recurring event.
numOccurrences	Number	Specifies how many times a recurring event should occur. Used when recurrenceEnd is set to NumOccurrences.
startDate	DateTime	Specifies the start date of the recurrence series.
endDate	DateTime	Specifies the end date of the recurrence series. Used when recurrenceEnd is set to EndDate.

To programmatically create and visualize a recurrent event, a Recurrence object must be created and assigned to a newly created or already existing Item in a Calendar. For example:

Note
More information about programmatically creating or accessing items on the client side, see here.

JavaScript

function createRecurrentEvent() {
    // creates the arguments object defining the recurrence series.
    var recurrenceData = {
        startDate: MindFusion.Common.DateTime.today(),
        pattern: MindFusion.Scheduling.RecurrencePattern.Monthly,
        monthlyRecurrence: MindFusion.Scheduling.MonthlyRecurrence.ByDayType,
        occurrence: MindFusion.Scheduling.Occurrence.Second,
        day: MindFusion.Scheduling.DayOfWeekType.Wednesday,
        months: 2,
        recurrenceEnd: MindFusion.Scheduling.RecurrenceEnd.EndDate,
        endDate: MindFusion.Common.DateTime.fromDateParts(2012, 11, 21)
    };

    // creates a new Recurrence from the arguments object.
    // This recurrent series will occur the second Wednesday of every 2 months effective 10/04/2011 until 12/21/2012.
    var recurrence = new MindFusion.Scheduling.Recurrence(recurrenceData);

    // creates the new item arguments data.
    var itemData = {
        subject: 'recurring event',
        startTime: MindFusion.Common.DateTime.today().addHours(12),
        endTime: MindFusion.Common.DateTime.today().addHours(14),
        recurrence: recurrence
    };

    // creates the new recurring event and generates its visible occurrences in the Calendar.
    var calendar = $find('Calendar1');
    calendar.createItem(itemData);
}

To assign a new recurrence series to an already existing item, use the editItem method of the Calendar. For example:

JavaScript

// the Item object to assign the recurrence series to is passed as parameter to this sample function.
function assignRecurrenceSeries(item) {
    // creates the arguments object defining the recurrence series.
    var recurrenceData = {
        startDate: MindFusion.Common.DateTime.today().addDays(1),
        pattern: MindFusion.Scheduling.RecurrencePattern.Daily,
        dailyRecurrence: MindFusion.Scheduling.DailyRecurrence.EveryWorkday,
        recurrenceEnd: MindFusion.Scheduling.RecurrenceEnd.NumOccurrences,
        numOccurrences: 25
    };

    // creates a new Recurrence from the arguments object.
    // This recurrent series will occur every weekday effective 10/05/2011 until 11/08/2011.
    var recurrence = new MindFusion.Scheduling.Recurrence(recurrenceData);

    // wraps the recurrence as item changes in an object, passed as parameter to the editItem method.
    var itemData = {
        recurrence: recurrence
    };

    // attaches the new recurring series to the existing and generates its visible occurrences in the Calendar.
    var calendar = $find('Calendar1');
    calendar.editItem(item, itemData);
}

Editing recurrences

In order to edit a recurrence pattern, you must first update the original Recurrence object by calling editRecurrence and then update the master Item of the recurrence series by calling editItem. The following example shows how to change the RecurrenceEnd of an existing recurrence:

JavaScript

function editRecurrenceSeries(itemWithRecurrence) {
    var calendar = $find('Calendar1');
    
    // get a reference to the original recurrence object.
    var originalRecurrence = itemWithRecurrence.getRecurrence();

    // get a reference to the recurrence master item.
    var masterItem = originalRecurrence.getMaster();

    // edit the original recurrence/
    var editedRecurrence = calendar.editRecurrence(originalRecurrence, {recurrenceEnd: MindFusion.Scheduling.RecurrenceEnd.Never});

    // finally edit the master item by providing the edited recurrence as argument.
    calendar.editItem(masterItem, {recurrence: editedRecurrence});
}

Deleting recurrences

To remove a recurrent series from an Item, just call editItem and set recurrence to null in the args parameter. Like this:

Note
After removing a Recurrence from an Item, the original item used for creating the recurrent series will be restored. To delete the recurrence series and the original item use deleteItem instead (see Manipulating Items on the Client).

JavaScript

// the occurrence parameter is an Item instance, representing an occurrence in the recurrence series to be removed.
function removeRecurrence(occurrence) {
    // gets a reference to the calendar object.
    var calendar = $find('Calendar1');

    // edits the item by removing the recurrence.
    calendar.editItem(occurrence, {recurrence: null});
}

Accessing occurrences. Exceptions

Items, which are part of a recurrence series are easily distinguishable from regular events by checking the value of their getRecurrenceState method. Occurrences defined in the time range, currently presented by the Calendar, can be obtained by calling getItems and filter the result by the master item's id and the occurrence's occurrenceIndex. Exceptions can be retrieved through the getExceptions function.