CalendarRepeatRule

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


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);
}


Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
dayInMonth           Y 
dayInWeek           Y 
exceptionDates           Y 
expires           Y 
frequency           Y 
interval           Y 
monthInYear           Y 
numberOfOccurrences           Y 
weekInMonth           Y 
SUNDAY           Y 
MONDAY           Y 
TUESDAY           Y 
WEDNESDAY           Y 
THURSDAY           Y 
FRIDAY           Y 
SATURDAY           Y 
LAST_DAY_IN_MONTH           Y 
FREQUENCY_DAILY           Y 
FREQUENCY_WEEKLY           Y 
FREQUENCY_MONTHLY           Y 
FREQUENCY_MONTHLY_AT_A_WEEK_DAY           Y 
FREQUENCY_YEARLY           Y 
FREQUENCY_YEARLY_AT_A_WEEK_DAY_OF_MONTH           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.pim.calendar" />           Y 

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Properties

Number dayInMonth
Number dayInWeek
Date[] exceptionDates
Date expires
String frequency
Number interval
Number monthInYear
Number numberOfOccurrences
Number weekInMonth

Properties

Number dayInMonth


Day of month when a recurrence repeats.
This is only meaningful when frequency is:

  • monthly or
  • yearly


Supported Platforms
 - BlackBerry 10

Number 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 SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, and SATURDAY.

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


Supported Platforms
 - BlackBerry 10

Date[] exceptionDates


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


Supported Platforms
 - BlackBerry 10

Date expires


The date when the recurrence ends.
A finite recurrence should have an expiry date or a defined number of occurrences.


Supported Platforms
 - BlackBerry 10

String frequency


The frequency of the CalendarRepeatRule. Possible values are: FREQUENCY_DAILY, FREQUENCY_WEEKLY, FREQUENCY_MONTHLY, FREQUENCY_MONTHLY_AT_A_WEEK_DAY, FREQUENCY_YEARLY, or FREQUENCY_YEARLY_AT_A_WEEK_DAY_OF_MONTH


Supported Platforms
 - BlackBerry 10

Number 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.


Supported Platforms
 - BlackBerry 10

Number monthInYear


Month of the year when a recurrence repeats.
This is only meaningful when frequency is:

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


Supported Platforms
 - BlackBerry 10

Number numberOfOccurrences


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


Supported Platforms
 - BlackBerry 10

Number 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.


Supported Platforms
 - BlackBerry 10

Constants

static Number SUNDAY = 1


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


Supported Platforms
 - BlackBerry 10

static Number MONDAY = 2


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


Supported Platforms
 - BlackBerry 10

static Number TUESDAY = 4


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


Supported Platforms
 - BlackBerry 10

static Number WEDNESDAY = 8


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


Supported Platforms
 - BlackBerry 10

static Number THURSDAY = 16


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


Supported Platforms
 - BlackBerry 10

static Number FRIDAY = 32


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


Supported Platforms
 - BlackBerry 10

static Number SATURDAY = 64


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


Supported Platforms
 - BlackBerry 10

static Number LAST_DAY_IN_MONTH = 127


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


Supported Platforms
 - BlackBerry 10

static String FREQUENCY_DAILY


Indicates that a recurring event occurs daily.


Supported Platforms
 - BlackBerry 10

static String FREQUENCY_WEEKLY


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


Supported Platforms
 - BlackBerry 10

static String FREQUENCY_MONTHLY


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


Supported Platforms
 - BlackBerry 10

static String FREQUENCY_MONTHLY_AT_A_WEEK_DAY


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


Supported Platforms
 - BlackBerry 10

static String FREQUENCY_YEARLY


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


Supported Platforms
 - BlackBerry 10

static String 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.


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:03 GMT-0500 (EST)