Calendar
The Calendar object provides functions for creating and finding events.
Since: BlackBerry WebWorks 2.0
Installation:
To use this API in your project, add the calendar plugin:
webworks plugin add com.blackberry.pim.calendar
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].
createEvent()
Returns a new CalendarEvent object. This method does not persist the CalendarEvent object to the device. To persist the CalendarEvent object to the device, invoke CalendarEvent.save()
Synopsis:
CalendarEvent blackberry.pim.calendar.createEvent(properties, folder)
Parameters:
- properties {Object} optional
-
Optional object literal that specifies the field values for the CalendarEvent object. Any number of CalendarEvent properties may be provided.
- folder {CalendarFolder} optional
- Optional CalendarFolder object that contains the event. If no folder is specified, the event will be created in the default calendar.
Example:
<script type="text/javascript"> 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); } </script>
findEvents()
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.
Synopsis:
void blackberry.pim.calendar.findEvents(findOptions, onFindSuccess, onFindError)
Parameters:
- findOptions {CalendarFindOptions}
-
Options to be applied to the search.
- onFindSuccess {Function}
-
Success callback function that is invoked with the events returned from the calendar.
- onFindSuccess.events {CalendarEvent[]}
-
The array of CalendarEvent objects from the search.
- onFindError {Function} optional
-
error callback function. Invoked when error occurs.
- error {CalendarError}
-
The CalendarError object which contains the error 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); }
getCalendarAccounts()
Retrieves all calendar accounts.
Synopsis:
{CalendarAccount[]} blackberry.pim.calendar.getCalendarAccounts()
getDefaultCalendarAccount()
Retrieves the default calendar account.
Synopsis:
{CalendarAccount} blackberry.pim.calendar.getDefaultCalendarAccount()
getDefaultCalendarFolder()
Retrieves the default calendar folder.
Synopsis:
{CalendarFolder} blackberry.pim.calendar.getDefaultCalendarFolder()
getEvent()
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.
Synopsis:
{CalendarEvent} blackberry.pim.calendar.getEvent(eventId, folder)
Parameters:
- eventId {String}
-
The identifier of the event.
- folder {CalendarFolder}
-
The folder that contains this event.
Last modified: 2014-10-09
Got questions about leaving a comment? Get answers from our Disqus FAQ.
comments powered by Disqus