calendar by Trigger.io

Currently displaying version

calendar: Calendar manipulation

The forge.calendar namespace allows calendar events to be added to the native calendar

Config options

usage_description
This key lets you describe the reason your app accesses the user's calendars. When the system prompts the user to allow access, this string is displayed as part of the alert.

API

forge.calendar.addEvent(options, success, error)

iOS, Android

Show a UI that allows the user to add a calendar event, with certain properties pre-filled.

Parameters:
options
object parameters to define the event
success
function(eventId)
error
function(content) called with details of any error which may occur

The properties that can be set on the options object are:

  • title: The title of the event
  • description: The event description (appears as notes on iOS)
  • location: The location of the event
  • start: The time the event starts (a JavaScript Date object)
  • end: The time the event ends (a JavaScript Date object)
  • allday: A boolean value that determines whether the event is an all day event (the time of day in the start and end will be ignored in all day events)
  • recurring: Whether the event is recurring and how often, one of: not, daily, weekly, monthly, or yearly. If not specified the event will not recur.

Warning: On Android the eventId which is returned is the ID of the most recently added event, if another event happened to be added before the user returned to your app this ID could be incorrect.

Example:

forge.calendar.addEvent({
    title: "Anniversary of adding my first event",
    start: new Date(),
    end: new Date(),
    allday: true,
    recurring: "yearly"
}, function () {
    alert("Event added!");
});

forge.calendar.listCalendars(accessLevel, success, error)

iOS, Android

Get a list of the users calendars, primarily to be used in conjuction with forge.calendar.insertEvent, which requires a calendar id.

Parameters:
accessLevel
int only return calendars where the user has access higher than the given access level. (Android only)
success
function(calendars) called with an array of calendar objects, each containing id, name, and color properties
error
function(content) called with details of any error which may occur

The options for the accessLevel parameter are:

  • forge.calendar.ACL.none: cannot access the calendar
  • forge.calendar.ACL.freebusy: can only see free/busy information about the calendar
  • forge.calendar.ACL.read: can read all event details
  • forge.calendar.ACL.respond: can reply yes/no/maybe to an event
  • forge.calendar.ACL.override: default
  • forge.calendar.ACL.contributor: full access to modify the calendar, but not the access control settings
  • forge.calendar.ACL.editor: full access to modify the calendar, but not the access control settings
  • forge.calendar.ACL.owner: full access to the calendar
  • forge.calendar.ACL.root: domain admin

Example:

forge.calendar.listCalendars(forge.calendar.ACL.none, function (calendars) {
    calendars.forEach(function (calendar) {
        ...
    });
});

forge.calendar.insertEvent(details, success, error)

iOS, Android

Programmatically insert an event into the users calendar, this will not prompt the user or show a UI before inserting.

Parameters:
details
object parameters to define the event
success
function(eventId)
error
function(content) called with details of any error which may occur

When inserting an event the following fields are required:

  • calendar: The id of the calendar to insert into (use forge.calendar.listCalendars for a list of available calendars)
  • title: The title of the event
  • start: The time the event starts (a JavaScript Date object)
  • end: The time the event ends (a JavaScript Date object)

The following options fields can also be included:

  • description: The event description (appears as notes on iOS)
  • location: The location of the event
  • allday: A boolean value that determines whether the event is an all day event (the time of day in the start and end will be ignored in all day events)
  • recurring: Whether the event is recurring and how often, one of: not, daily, weekly, monthly, or yearly. If not specified the event will not recur.

forge.calendar.updateEvent(eventId, details, success, error)

iOS, Android

Programmatically update an existing event, this will update any of the details given for an existing event.

Parameters:
eventId
string id of the event to be updated
details
object parameters to update
success
function(eventId)
error
function(content) called with details of any error which may occur

When updating an event any combination of the following fields can be included in the details object:

  • title: The title of the event
  • start: The time the event starts (a JavaScript Date object)
  • end: The time the event ends (a JavaScript Date object)
  • description: The event description (appears as notes on iOS)
  • location: The location of the event
  • allday: A boolean value that determines whether the event is an all day event (the time of day in the start and end will be ignored in all day events)
  • recurring: Whether the event is recurring and how often, one of: not, daily, weekly, monthly, or yearly. If not specified the event will not recur.

forge.calendar.getEvent(eventId, success, error)

iOS, Android

Read info about a given eventId.

Parameters:
eventId
string id of the event to be loaded
success
function(eventDetails)
error
function(content) called with details of any error which may occur

The eventDetails object can contain the following fields:

  • id: The id of the event
  • calendar: The id of the calendar containing the event
  • title: The title of the event
  • start: The time the event starts (a JavaScript Date object)
  • end: The time the event ends (a JavaScript Date object)
  • description: The event description (appears as notes on iOS)
  • location: The location of the event
  • allday: A boolean value that determines whether the event is an all day event (the time of day in the start and end will be ignored in all day events)

forge.calendar.getEvents(options, success, error)

iOS, Android

Load data on all events in a given date range. See getEvent for details on returned fields.

Parameters:
options
object Contains either a from, to date or both to filter events
success
function(eventDetails) Called with an array of matching events
error
function(content) called with details of any error which may occur

forge.calendar.deleteEvent(eventId, success, error)

iOS, Android

Remove a given eventId from the users calendar.

Parameters:
eventId
string id of the event to be deleted
success
function()
error
function(content) called with details of any error which may occur

Warning: This will not prompt the user, Apple App Store guidelines require you prompt the user before performing a destructive action on the users calendar.

forge.calendar.editEvent(eventId, success, error)

iOS, Android

Display a UI allowing the user to edit an existing event based on the eventId

Parameters:
eventId
string id of the event to be edited
success
function()
error
function(content) called with details of any error which may occur

Warning: On many Android devices there is a bug with the UI to edit calendar events which means the user will be shown the event but will be unable to edit most fields. This API method is only really safe to use on iOS, if you want the user to be able to edit events on Android then you should create your own UI using forge.calendar.getEvent and forge.calendar.updateEvent.