Calendar

The Calendar object provides functions for creating and finding events.

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. The object should be in the following form (with any number of properties):

folder{Object[]}
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-05-14



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

comments powered by Disqus