Calendar

The Calendar object provides functions for creating and finding contacts.


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 Sun Dec 30 2012 18:15:32 GMT-0500 (EST)