Calendar

The Calendar object provides functions for creating and finding contacts.


Learning Resources:

Sample - Using Calendar API to create and modify calendar entries Sample that demonstrates how to use the BlackBerry Calendar API [BlackBerry on GitHub].

Supported Platform(s)

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+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>access_pimdomain_calendars</rim:permit>
Permits your app to access calendar.

Functions

static blackberry.pim.calendar.CalendarEvent blackberry.pim.calendar.createEvent (properties : Object, [folder : blackberry.pim.calendar.CalendarFolder])


Returns a new blackberry.pim.calendar.CalendarEvent object. This method does not persist the CalendarEvent object to the device. To persist the CalendarEvent object to the device, invoke save().


Supported Platforms
 - BlackBerry 10


Parameters
properties Optional object literal that specifies the field values for the CalendarEvent object. The object should be in the following form (with any number of properties):
folder Optional CalendarFolder object that contains the event. If no folder is specified, the event will be created in the default calendar.

Code Example:
var evt,
    calendar = blackberry.pim.calendar;

function onSaveSuccess(created) {
   // set evt to the object returned in save success callback, which
   // contains the persisted event id
   evt = created;
   alert("Event saved to device: " + evt.id);
}

function onSaveError(error) {
   alert("Error saving event to device: " + error.code);
}

function createEventInDefaultCalendarFolder(summary, location) {
   evt = calendar.createEvent({
       "summary": summary,
       "location": location,
       "start": new Date("Jan 01, 2015, 12:00"),
       "end": new Date("Jan 01, 2015, 12:30"),
       // if timezone is specified explicitly, then the times will be
       // for that particular timezone; otherwise, the times will be
       // for the current device timezone
       "timezone": "America/New_York"
   });
   evt.save(onSaveSuccess, onSaveError);
}

static void blackberry.pim.calendar.findEvents (findOptions : blackberry.pim.calendar.CalendarFindOptions, onFindSuccess : function, [onFindError : function])


Find calendar event(s) in the calendar based on some criteria. This function can be used to look up events based on start/end time, location, or summary.


Supported Platforms
 - BlackBerry 10


Parameters
findOptions Options to be applied to the search.
onFindSuccess Success callback function that is invoked with the events returned from the calendar.

events: The array of CalendarEvent objects from the search.
onFindError Optional error callback function. Invoked when error occurs.

error: The CalendarError object which contains the error code.

Code Example:
var calendar = blackberry.pim.calendar,
    CalendarFindOptions = calendar.CalendarFindOptions;

function onFindSuccess(events) {
   alert("Found " + events.length + " events!");
   events.forEach(function (evt) {
      alert("Event summary: " + evt.summary);
      alert("Event location: " + evt.location);
   });
}

function onFindError(error) {
   alert("Error: " + error.code);
}

// Find any events by keyword in any of the following fields:
// -location
// -summary
// -attendees' names or emails
function findEventsByKeyword(keyword) {
   var filter = { "substring" : keyword };
   var findOptions = {
       "filter" : filter,
       "detail" : CalendarFindOptions.DETAIL_FULL
   };

   // Find all events that has the specified keyword in summary,
   // location or attendees' name/email
   calendar.findEvents(findOptions, onFindSuccess, onFindError);
}

function findEventsSortSummaryDescending(keyword) {
   var filter = { "substring" : keyword };
   var findOptions = {
       "filter" : filter,
       "sort": [{
          "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
          "desc": true
       }],
       "detail" : CalendarFindOptions.DETAIL_FULL
   };

   calendar.findEvents(findOptions, onFindSuccess, onFindError);
}

// Only events in the specified folder will be returned in search results
function findEventsInCalendarFolder(keyword, folder, limit) {
   var filter = {
       "substring": keyword,
       "folders": [folder]
   };
   var findOptions = {
       "filter": filter,
       "sort": [{
          "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
          "desc": false
       }],
       "detail": CalendarFindOptions.DETAIL_AGENDA,
       "limit": limit
   };

   calendar.findEvents(findOptions, onFindSuccess, onFindError);
}

// Filter is optional in search
function listAllEvents(limit) {
   var findOptions = {
       "sort": [{
          "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
          "desc": false
       }],
       "detail": CalendarFindOptions.DETAIL_AGENDA,
       "limit": limit
   };

   calendar.findEvents(findOptions, onFindSuccess, onFindError);
}

static blackberry.pim.calendar.CalendarAccount[] blackberry.pim.calendar.getCalendarAccounts ()


Retrieves all calendar accounts.


Supported Platforms
 - BlackBerry 10

static blackberry.pim.calendar.CalendarAccount blackberry.pim.calendar.getDefaultCalendarAccount ()


Retrieves the default calendar account.


Supported Platforms
 - BlackBerry 10

static blackberry.pim.calendar.CalendarFolder blackberry.pim.calendar.getDefaultCalendarFolder ()


Retrieves the default calendar folder.


Supported Platforms
 - BlackBerry 10

static blackberry.pim.calendar.CalendarEvent blackberry.pim.calendar.getEvent (eventId : String, folder : blackberry.pim.calendar.Folder)


Retrieves the event with specified eventId and folder. This function is especially useful if you have previously obtained an event object, and you want to get a fresh copy from the backend to make sure all its properties are up-to-date.


Supported Platforms
 - BlackBerry 10


Parameters
eventId The identifier of the event
folder the folder that contains this event
Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:03 GMT-0500 (EST)