CalendarRepeatRule

The CalendarRepeatRule object represents the recurrence of a calendar event item.

Installation:

To use this API in your project, add the calendar plugin:

webworks plugin add com.blackberry.pim.calendar

Code Example:

var calendar = blackberry.pim.calendar,
    CalendarRepeatRule = calendar.CalendarRepeatRule,
    recEvent;

function onSaveSuccess(saved) {
    alert("Event saved successfully: " + saved.id);
    recEvent = saved;
}

function onSaveError(error) {
    alert("Event not saved, error code: " + error.code);
}

// Create an event that repeats every month for 4 times
function createEventRepeatEveryMonth() {
   var start = new Date("Jan 6, 2013, 12:00"),
       end = new Date("Jan 6, 2013, 12:30"),
       summary = "Every month",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_MONTHLY,
           "expires": new Date("Dec 31, 2013"),
           "numberOfOccurrences": 4
       };

   recEvent = calendar.createEvent({"summary": summary, "start": start, "end": end, "recurrence": rule});
   recEvent.save(onSaveSuccess, onSaveError);
}

// Create an event that repeats every month, sets explicit expiry date
// the event will only have 3 occurrences since the expiry date
// is before the 4th occurrence
function createEventRepeatEveryMonthExpire() {
   var start = new Date("Jan 7, 2013, 12:00"),
       end = new Date("Jan 7, 2013, 12:30"),
       venue = "some location",
       summary = "Every month binding expiry date",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_MONTHLY,
           "expires": new Date("Mar 30, 2013"),
           "numberOfOccurrences": 4
       };

   recEvent = calendar.createEvent({"summary": summary, "location": venue, "start": start, "end": end, "recurrence": rule});
   recEvent.save(onSaveSuccess, onSaveError);
}

// Create an event that repeats every week on Monday and Wednesday
function createEventRepeatEveryMonWed() {
   var start = new Date("Jan 21, 2013, 12:00"),
       end = new Date("Jan 21, 2013, 12:30"),
       venue = "some location",
       summary = "Every Mon and Wed",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_WEEKLY,
           "expires": new Date("Mar 30, 2013"),
           "dayInWeek": CalendarRepeatRule.MONDAY | CalendarRepeatRule.WEDNESDAY
       };

   recEvent = calendar.createEvent({"summary": summary, "location": venue, "start": start, "end": end, "recurrence": rule});
   recEvent.save(onSaveSuccess, onSaveError);
}

// Create an event that repeats on first Friday every month
function createEventFirstFriEveryMonth() {
   var start = new Date("Feb 1, 2013, 12:00"),
       end = new Date("Feb 1, 2013, 12:30"),
       venue = "some location",
       summary = "First Fri every month",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_MONTHLY_AT_A_WEEK_DAY,
           "expires": new Date("Jun 30, 2013"),
           "dayInWeek": CalendarRepeatRule.FRIDAY,
           "weekInMonth": 1
       };

  recEvent = calendar.createEvent({"summary": summary, "location": venue, "start": start, "end": end, "recurrence": rule});
  recEvent.save(onSaveSuccess, onSaveError);
}

// Create an event that repeats on the first Friday of the seventh
// month every year
function createEventFirstFriSeventhMonthEveryYear() {
   var start = new Date("Jul 5, 2013, 12:00"),
       end = new Date("Jul 5, 2013, 12:30"),
       venue = "some location",
       summary = "First Fri of seventh month every year",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_YEARLY_AT_A_WEEK_DAY_OF_MONTH,
           "expires": new Date("Jun 30, 2017, 12:00"),
           "dayInWeek": CalendarRepeatRule.FRIDAY,
           "weekInMonth": 1,
           "monthInYear": 7
       };

  recEvent = calendar.createEvent({"summary": summary, "location": venue, "start": start, "end": end, "recurrence": rule});
  recEvent.save(onSaveSuccess, onSaveError);
}

// Create an event that repeats on the last day of
// every month with 4 occurrences
function createEventRepeatsLastDayOfEveryMonth() {
   var start = new Date("Jan 31, 2013, 12:00"),
       end = new Date("Jan 31, 2013, 12:30"),
       venue = "some location",
       summary = "Last day of each month with 4 occurrences",
       rule = {
           "frequency": CalendarRepeatRule.FREQUENCY_MONTHLY_AT_A_WEEK_DAY,
           "numberOfOccurrences": 4,
           "dayInWeek": CalendarRepeatRule.LAST_DAY_IN_MONTH
       };

  recEvent = calendar.createEvent({"summary": summary, "location": venue, "start": start, "end": end, "recurrence": rule});
  recEvent.save(onSaveSuccess, onSaveError);
}
            
Properties:
Number dayInMonth
Number dayInWeek
Date[] exceptionDates
Date expires
String frequency
Number interval
Number monthInYear
Number numberOfOccurrences
Number weekInMonth

dayInMonth

Day of month when a recurrence repeats.

This is only meaningful when frequency is:

  • monthly or
  • yearly

Synopsis:

Number CalendarRepearRule.dayInMonth

dayInWeek

Days of the week when a recurrence repeats.

This is only meaningful when the frequency is:

  • weekly,
  • monthly at a certain day of a certain week, or
  • yearly at a certain day of a certain week of a certain month

Each day of the week has a corresponding value. The values can be OR'ed together to have rules with multiple days.

Refer to CalendarRepeatRule.SUNDAY, CalendarRepeatRule.MONDAY, CalendarRepeatRule.TUESDAY, CalendarRepeatRule.WEDNESDAY, CalendarRepeatRule.THURSDAY, CalendarRepeatRule.FRIDAY, and CalendarRepeatRule.SATURDAY.

If an event should repeat on the last day of every month, you should set this field to CalendarRepeatRule.LAST_DAY_IN_MONTH

Synopsis:

Number CalendarRepearRule.dayInWeek

exceptionDates

One or more dates and times to which the CalendarRepeatRule does not apply.

Synopsis:

Date[] CalendarRepearRule.exceptionDates

expires

The date when the recurrence ends.

A finite recurrence should have an expiry date or a defined number of occurrences.

Synopsis:

Date CalendarRepearRule.expires

interval

The interval is the number of times a rule must generate a possible date to produce an occurrence.

A recurrence rule and a start date yield a set of possible dates. For example, a daily event that repeats five times starting at July 23rd 2012 has five possible dates.

With the default interval value of one, the occurrences for this event will be the 23rd, 24th, 25th, 26th and 27th. With a value of two, the occurrences will be 24th, 26th, 28th, 30th and 1st of August.

Synopsis:

Number CalendarRepearRule.interval

monthInYear

This is only meaningful when frequency is:

This is only meaningful when frequency is:

  • yearly or
  • yearly at a certain day of a certain week of a certain month

Synopsis:

Number CalendarRepearRule.monthInYear

numberOfOccurrences

The number of repetitions in a finite recurrence.

A finite recurrence should have an expiry date or a defined number of occurrences.

Synopsis:

Number CalendarRepearRule.numberOfOccurences

weekInMonth

Week in the month when a recurrence repeats.

This is only meaningful when frequency is:

  • monthly at a certain day of a certain week or
  • yearly at a certain day of a certain week of a certain month

For example, the recurrence rule for an event on the second Sunday of May would have a value of 2 in this attribute.

Synopsis:

Number CalendarRepearRule.weekInMonth

SUNDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.SUNDAY = 1

MONDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.MONDAY = 2

TUESDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.TUESDAY = 4

WEDNESDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.WEDNESDAY = 8

THURSDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.THURSDAY = 16

FRIDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.FRIDAY = 32

SATURDAY

Used for specifying a recurrence that involves day of the week.

Synopsis:

constant
Number CalendarRepeatRule.SATURDAY = 64

LAST_DAY_IN_MONTH

Used for specifying a recurrence that involves last day in the month.

Synopsis:

constant
Number CalendarRepeatRule.LAST_DAY_IN_MONTH = 127

FREQUENCY_DAILY

Indicates that a recurring event occurs daily.

Synopsis:

constant
String CalendarRepeatRule.FREQUENCY_DAILY = "daily"

FREQUENCY_WEEKLY

Indicates that a recurring event should happen on specific days of the week.

Synopsis:

constant
String CalendarRepeatRule.FREQUENCY_WEEKLY = "weekly"

FREQUENCY_MONTHLY

Indicates that a recurring event that happens at a given day of every month.

Synopsis:

constant
String CalendarRepeatRule.FREQUENCY_MONTHLY = "monthly"

FREQUENCY_MONTHLY_AT_A_WEEK_DAY

Indicates that a recurring event happens every month at a certain day of a certain week.

Synopsis:

constant
Number CalendarRepeatRule.FREQUENCY_MONTHLY_AT_A_WEEK_DAY = "monthlyAtWeekDay"

FREQUENCY_YEARLY

Indicates that a recurring event that happens every year at a given day of a month.

Synopsis:

constant
Number CalendarRepeatRule.FREQUENCY_YEARLY = "yearly"

FREQUENCY_YEARLY_AT_A_WEEK_DAY_OF_MONTH

Indicates that a recurring event that happens at a certain day of a given week of a certain month of the year.

Synopsis:

constant
String CalendarRepeatRule.FREQUENCY_YEARLY_AT_A_WEEK_DAY_OF_MONTH = "yearlyAtWeekDayOfMonth"

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus