Telerik UI for Windows 8 HTML

RadScheduler supports event recurrence with various options for the recurrence rules. This article will introduce you to recurring events and will provide explanation on how you can create different recurrence rules following the iCal specification.

This topic contains the following sections.

Recurring Events

Recurring events are those that are repeated in time. The recurrences are defined by a recurrence rules. The user can create a recurring event or configure an existing event to be recurring by using the built-in event editing form. The editing form provides four basic recurrence options: daily, weekly, monthly and yearly. Once an event is configured as recurring it gets a ring arrow icon identifying it as a series of events and it gets repeated based on the recurrence rule.

Figure 1: Weekly Recurring Event.


Creating Recurrence Rules

To set a custom recurrence rule, use the recurrenceRule event property. The property accepts a string in the format described in the iCal specification and allows the creation of diverse recurrence rules. The rule consists of rule parts divided by а semicolon. The FREQ part is mandatory and the rest are optional, but must not occur more than once. Here is a list of the rule parts you can use with brief descriptions and examples:

  • FREQ: This is the rule that defines the base repetition logic and is mandatory. Possible values for RadScheduler are daily, weekly, monthly and yearly.

    Code Listing 1: FREQ Rule Copy imageCopy
    recurrenceRule: "FREQ=DAILY",
  • UNTIL: With this rule part you can specify that the rest of the rule will stop at a given date. This rule cannot be used together with the COUNT rule. This rules accepts a date string in the format YYYY-MM-DD.

    Code Listing 2: UNTIL Rule Copy imageCopy
    recurrenceRule: "FREQ=WEEKLY;UNTIL=2013-06-20",
  • COUNT: This rule takes a number as a value and specifies how many events the rule will generate.

    Code Listing 3: COUNT Rule Copy imageCopy
    recurrenceRule: "FREQ=MONTHLY;COUNT=3",
  • INTERVAL: This rule takes a number as a value and specifies a skip step. For example, if the frequency is weekly and the interval is 3, then the scheduler will skip two weeks and place the next event on the fourth week.

    Code Listing 4: INTERVAL Rule Copy imageCopy
    recurrenceRule: "FREQ=DAILY;INTERVAL=3",
  • BYDAY: With this rule you can specify if you want the recurrence to happen on specific weekdays. The available values are MO, TU, WE, TH, FR, SA, SU corresponding to the days of the week. This rule can accept multiple values separated by a comma.

    Code Listing 5: BYDAY Rule Copy imageCopy
    recurrenceRule: "FREQ=DAILY;BYDAY=MO,FR",
  • BYMONTHDAY: This rule takes a number from 1 to 31 as a value and specifies for which days of the month the rule will apply. This rule can accept multiple values separated by a comma.

    Code Listing 6: BYMONTHDAY Rule Copy imageCopy
    recurrenceRule: "FREQ=DAILY;BYMONTHDAY=7,14,17",
  • BYMONTH: This rule takes a number from 1 to 12 as a value and specifies for which months of the year the rule will apply.

    Code Listing 7: BYMONTH Rule Copy imageCopy
    recurrenceRule: "FREQ=WEEKLY;BYMONTH=3,5,8",

You can create complex recurrence rules by using multiple rule parts together. Code Listing 2 depicts the scenario where you want your event to repeat every second week Tuesday and Thursday and only in the months of May and June.

Code Listing 8: Complex Recurrence Rule Copy imageCopy

Setting Recurrence Exceptions

To allow creation of the most complex recurrence scenarios, RadScheduler allows you to specify exceptions to the recurrence rule in the form of datetimes. To not show the event, the exception datetime should match the starting datetime of the recurring event's instance. The recurrence exceptions should be a string of semicolon separated dates in the format yyyyMMddTHHmmssZ. The time part of the datetimes should always be in UTC timezone.

Code Listing 9: Setting Recurrence Exceptions Copy imageCopy
start: new Date("2013/06/06 10:30"),
end: new Date("2013/06/06 11:00"),
recurrenceRule: "FREQ=DAILY",
// note that the exceptions time 07:30 matches the start time 10:30 because the exceptions are in UTC timezone.
recurrenceException: "20130607T073000Z;20130608T073000Z",