Calendar: Managing Calendars and Calendar Events

This tutorial demonstrates how you can manage calendars in the device to access, modify, add, and remove calendar items within a specified calendar on the device.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Calendar API basics by learning about:

• Creating a Calendar

  Create a new calendar using the Calendar constructor.

• Events
  • Adding Events to a Calendar

    Add events to the default calendar, and define an alarm and recurrence rule for an event.

  • Adding Events to a Calendar in the Batch Mode

    Add events to the default calendar in the batch mode.

  • Managing a Single Calendar Event

    Update and delete an existing calendar event.

  • Updating Recurring Calendar Events

    Update a single instance of a recurring event.

  • Managing Multiple Calendar Events in the Batch Mode

    Update and delete calendar events in the batch mode.

  • Converting Calendar Event Formats

    Convert a calendar event to the iCalendar format and back.

• Tasks
  • Adding Tasks to a Calendar

    Add tasks to the default calendar, and define an alarm for a task.

  • Adding Tasks to a Calendar in the Batch Mode

    Add tasks to the default calendar in the batch mode.

  • Managing a Single Calendar Task

    Update and delete an existing calendar task.

  • Managing Multiple Calendar Tasks in the Batch Mode

    Update and delete calendar tasks in the batch mode.

  • Converting Calendar Task Formats

    Convert a calendar task to the iCalendar format and back.

• Receiving Notifications on Calendar Changes

  Receive notifications when calendar items are added, updated, or deleted.

Task

In the Event Manager task, we will walk through how to manage calendar events in your application.

Creating a Calendar

Creating a new calendar is a basic calendar management skill:

Note
The created calendar is associated with a specified account. Therefore, you must retrieve the account before creating a new calendar.

1. Declare a variable to store the created calendar:

   var myCalendar = null;

2. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new Calendar object.

   Add the new calendar to the system using the addCalendar() method of the CalendarManager interface:

   function getAccountsSuccess(accounts)
   {
      var account = accounts[0];
      if (account)
      {
         /* New calendar can be created and added */
         myCalendar = new tizen.Calendar(account.id, "remote calendar", "TASK");
         tizen.calendar.addCalendar(myCalendar);
         console.log("New calendar created with ID=" + myCalendar.id);
      }
   }

3. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above:

   tizen.account.getAccounts(getAccountsSuccess, function(err));
   

Adding Events to a Calendar

To create engaging applications with various calendar features, you must learn to add events to calendars:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as an event.

   var calendar = tizen.calendar.getDefaultCalendar("EVENT");
   

2. Create a CalendarEvent object and define the event properties:

   var ev = new tizen.CalendarEvent
   ({
      description:"HTML5 Introduction",
      summary:"HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      duration: new tizen.TimeDuration(1, "HOURS"),
      location:"Huesca",
   

3. To make a recurring event, define a recurrence rule.

   In this example, the event repeats once a day for 3 days.

      recurrenceRule: new tizen.CalendarRecurrenceRule("DAILY", {occurrenceCount: 3})
   });
   

4. To set up an alarm to remind the user about the event, create an alarm with the CalendarAlarm interface, and add the alarm to the event:

   /* Alarm is triggered with sound 30 minutes before the event start time */
   var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
   
   ev.alarms = [alarm];
   

5. Add the CalendarEvent object to the default calendar with the add() method of the Calendar object.

   calendar.add(ev);  /* ev.id attribute is generated */

Adding Events to a Calendar in the Batch Mode

To create engaging applications with various calendar features, you must learn to add events to calendars in the batch mode:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

   var calendar = tizen.calendar.getDefaultCalendar("EVENT");
   

2. Define the items to be added as an array:

   var ev = new tizen.CalendarEvent
   ({
      description:"HTML5 Introduction",
      summary:"HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      duration: new tizen.TimeDuration(1, "HOURS"),
      location:"Huesca"
   });
   

   Note
   To keep the example as simple as possible, the array above includes only 1 event.

3. Use the addBatch() method of the Calendar object to add the events in the array to the calendar:

   calendar.addBatch([ev]);
   

   Note
   The addBatch() method is asynchronous, and its callbacks must be used to react to the success or failure of the operation.

Managing a Single Calendar Event

To create engaging applications with various calendar features, you must learn to manage a single calendar event:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as event.

   var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
   

2. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

   myCalendar.find(eventSearchSuccessCallback);

   Note
   To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes). In this example, all the events are retrieved because no filter is used.

3. Update or delete the found item inside the eventSearchSuccessCallback() event handler.

   In this example, the description parameter of the first event is changed and the event is updated in the calendar using the update() method. The second event is deleted using the remove() method.

   /* Define the event success callback */
   function eventSearchSuccessCallback(events)
   {
      /* Update the first existing event */
      events[0].description = "New Description";
      myCalendar.update(events[0]);
   
      /* Delete the second existing event */
      myCalendar.remove(events[1].id);
   }

Updating Recurring Calendar Events

To create engaging applications with various calendar features, you must learn to update recurring calendar events:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   Retrieve the calendar event using the get() method by specifying the event ID.

   var calendar = tizen.calendar.getDefaultCalendar("EVENT");
   var event = calendar.get(evId);
   

2. Expand the recurring event to get its instances by using the expandRecurrence() method of the CalendarEvent object:

   event.expandRecurrence(new tizen.TZDate(2012, 2, 1), new tizen.TZDate(2012, 2, 15),
                          eventExpandSuccessCB);

   The expanded event instances have their own id.uid and id.rid attributes, where the id.uid attribute is the same for all instances.

3. Update a single instance of the expanded recurring event.

   In case of recurring events, you can use the second parameter of the update() method to determine whether a single instance or all occurrences of the event are updated. If the parameter is set to true, all instances are updated, while if it is set to false, only the indicated instance of the recurring event is updated (based on the id.rid attribute).

   In this example, the second instance of the event is updated.

   /* Success event handler */
   function eventExpandSuccessCB(events)
   {
      events[1].summary = 'updated summary';
      calendar.update(events[1], false);
   }
   

Managing Multiple Calendar Events in the Batch Mode

To create engaging applications with various calendar features, you must learn to manage multiple calendar events in the batch mode:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as event.

   var myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
   

2. Retrieve all events stored in the calendar by using the find() method of the Calendar object:

   myCalendar.find(eventSearchSuccessCallback, errorCallback);

   Note
   To retrieve a specific set of events, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes). In this example, all the events are retrieved because no filter is used.

3. To update events:

   1. Define the items to be updated in the success event handler of the find() method:

      function eventSearchSuccessCallback(events)
      {
         events[0].description = "New Description 1";
         events[1].description = "New Description 2";
      

   2. Use the updateBatch() method to update multiple calendar items asynchronously:

         /* Update the first 2 existing events */
         myCalendar.updateBatch(events.slice(0, 2));
      }
      

4. To delete events, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

   function eventSearchSuccessCallback(events)
   {
      /* Delete the first 2 existing events */
      myCalendar.removeBatch([events[0].id, events[1].id]);
   }
   

Converting Calendar Event Formats

The following examples illustrate how to make calendar event exchange more efficient in your application by converting the calendar events to iCalendar format or the other way around using the CalendarEvent constructor and the convertToString() method of the Calendar object respectively:

• To convert an iCalendar string to a calendar event:

  1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

     With the parameter, specify the calendar type as event.

     var calendar = tizen.calendar.getDefaultCalendar("EVENT");

  2. Create a new CalendarEvent object from the iCalendar string and add it to the default calendar:

     try
     {
        var ev = new tizen.CalendarEvent
        (
           "BEGIN:VCALENDAR\r\n" +
           "BEGIN:VEVENT\r\n" +
           "DTSTAMP:19970901T1300Z\r\n" +
           "DTSTART:19970903T163000Z\r\n" +
           "DTEND:19970903T190000Z\r\n" +
           "SUMMARY:Tizen, Annual Employee Review\r\n" +
           "CATEGORIES:BUSINESS,HUMAN RESOURCES\r\n" +
           "END:VEVENT\r\n" +
           "END:VCALENDAR", "ICALENDAR_20"
        );
     
        calendar.add(ev);
        console.log('Event added with UID ' + ev.id.uid);
     }

  To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the events at once in a batch mode.

• To convert a calendar event to the iCalendar format:
  1. Get the default calendar and find all calendar events which include the "Tizen" string in the Summary attribute:

     var myCalendar;
     
     myCalendar = tizen.calendar.getDefaultCalendar("EVENT");
     
     /* Define a filter */
     var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
     
     /* Search for the events */
     myCalendar.find(eventSearchSuccessCallback, errorCallback, filter);
     

  2. Convert a calendar event to an iCalendar string in the success event handler of the find() method using the convertToString() method:

     function eventSearchSuccessCallback(events)
     {
        /* Convert the first event */
        var vevent = events[0].convertToString("ICALENDAR_20");
     }
     

  To export and convert multiple events from a calendar, find the required events using the find() method with an applicable filter, and then convert the found events one by one.

Adding Tasks to a Calendar

To create engaging applications with various calendar features, you must learn to add tasks to calendars:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as task.

   var calendar = tizen.calendar.getDefaultCalendar("TASK");
   

2. Create a CalendarTask object and define the task properties:

   var task = new tizen.CalendarTask
   ({
      description:"HTML5 Introduction",
      summary:"HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 10, 10, 0),
      dueDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      completedDate: new tizen.TZDate(2011, 3, 20, 10, 0),
      location:"Huesca"
   });
   

3. To set up an alarm to remind the user about the task, create an alarm with the CalendarAlarm interface, and add the alarm to the task:

   /* Alarm is triggered with sound 30 minutes before the task start time */
   var alarm = new tizen.CalendarAlarm(new tizen.TimeDuration(30, "MINS"), "SOUND");
   
   task.alarms = [alarm];
   

4. Add the CalendarTask object to the default calendar with the add() method of the Calendar object:

   calendar.add(task);  /* task.id attribute is generated */

Adding Tasks to a Calendar in the Batch Mode

To create engaging applications with various calendar features, you must learn to add tasks to calendars in the batch mode:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface:

   var calendar = tizen.calendar.getDefaultCalendar("TASK");
   

2. Define the items to be added as an array:

   var task = new tizen.CalendarTask
   ({
      description:"HTML5 Introduction",
      summary:"HTML5 Webinar",
      startDate: new tizen.TZDate(2011, 3, 30, 10, 0),
      dueDate: new tizen.TZDate(2011, 5, 30, 10, 0),
      completedDate: new tizen.TZDate(2011, 4, 30, 10, 0),
      location:"Huesca"
   });
   

   Note
   To keep the example as simple as possible, the array above includes only 1 task.

3. Use the addBatch() method of the Calendar object to add the tasks in the array to the calendar:

   calendar.addBatch([task]);
   

   Note
   The addBatch() method is asynchronous, and its callbacks must be used if you want to react to the success or failure of the operation.

Managing a Single Calendar Task

To create engaging applications with various calendar features, you must learn to manage a single calendar task:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as task.

   var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
   

2. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

   myCalendar.find(taskSearchSuccessCallback);

   Note
   To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes). In this example, all the tasks are retrieved because no filter is used.

3. Update or delete the found item inside the taskSearchSuccessCallback() event handler.

   In this example, the description parameter of the first task is changed and the task is updated in the calendar using the update() method. The second task is deleted using the remove() method.

   /* Define the event success callback */
   function taskSearchSuccessCallback(tasks)
   {
      /* Update the first existing task */
      tasks[0].description = "New Description";
      myCalendar.update(tasks[0]);
   
      /* Delete the second existing task */
      myCalendar.remove(tasks[1].id);
   }

Managing Multiple Calendar Tasks in the Batch Mode

To create engaging applications with various calendar features, you must learn to manage multiple calendar tasks in the batch mode:

1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

   With the parameter, specify the calendar type as task.

   var myCalendar = tizen.calendar.getDefaultCalendar("TASK");
   

2. Retrieve all tasks stored in the calendar by using the find() method of the Calendar object:

   myCalendar.find(taskSearchSuccessCallback);

   Note
   To retrieve a specific set of tasks, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Calendar Filter Attributes). In this example, all the tasks are retrieved because no filter is used.

3. To update tasks:

   1. Define the items to be updated in the success event handler of the find() method:

      function taskSearchSuccessCallback(tasks)
      {
         tasks[0].description = "New Description 1";
         tasks[1].description = "New Description 2";
      

   2. Use the updateBatch() method to update multiple calendar items asynchronously:

         /* Update the first 2 existing tasks */
         myCalendar.updateBatch(tasks.slice(0, 2));
      }
      

4. To delete tasks, use the removeBatch() method in the success event handler of the find() method to delete multiple calendar items asynchronously:

   function taskSearchSuccessCallback(tasks)
   {
      /* Delete the first 2 existing tasks */
      myCalendar.removeBatch([tasks[0].id, tasks[1].id]);
   }
   

Converting Calendar Task Formats

The following examples illustrate how to make calendar task exchange more efficient in your application by converting the calendar task to iCalendar format or the other way around using the CalendarTask constructor and the convertToString() method of the Calendar object respectively:

• To convert an iCalendar string to a calendar task:

  1. Retrieve the default system calendar using the getDefaultCalendar() method of the CalendarManager interface.

     With the parameter, specify the calendar type as task.

     var calendar = tizen.calendar.getDefaultCalendar("TASK");

  2. Create a new CalendarTask object from the iCalendar string and add it to the default calendar:

     var task = new tizen.CalendarTask
     (
        "BEGIN:VCALENDAR\r\n" +
        "VERSION:2.0\r\n" +
        "BEGIN:VTODO\r\n" +
        "DTSTAMP:TZID=CET:20110902T110000Z\r\n" +
        "DTSTART;TZID=CET:20110906T140000Z\r\n" +
        "DUE;TZID=CET:20110906T150000Z\r\n" +
        "SUMMARY:Tizen, discuss the schedule\r\n" +
        "DESCRIPTION:Find the feasible schedule\r\n" +
        "CATEGORIES:HUMAN RESOURCES\r\n" +
        "END:VTODO\r\n" +
        "END:VCALENDAR", "ICALENDAR_20"
     );
     
     calendar.add(task);
     console.log('Task added with id ' + task.id);
     

  To convert multiple strings and import them to a calendar, convert the strings one by one and then use the addBatch() method to add all the tasks at once in a batch mode.

• To convert a calendar task to the iCalendar format:
  1. Get the default calendar and find all calendar items which include the "Tizen" string in the Summary attribute:

     var myCalendar;
     
     myCalendar = tizen.calendar.getDefaultCalendar("TASK");
     
     /* Define a filter */
     var filter = new tizen.AttributeFilter("summary", "CONTAINS", "Tizen");
     
     /* Search for the tasks */
     myCalendar.find(taskSearchSuccessCallback, null, filter);
     

  2. Convert a calendar item to an iCalendar string in the success event handler of the find() method using the convertToString() method:

     function taskSearchSuccessCallback(tasks)
     {
        /* Convert the first task */
        var vtodo = tasks[0].convertToString("ICALENDAR_20");
     }
     

  To export and convert multiple tasks from a calendar, find the required tasks using the find() method with an applicable filter, and then convert the found tasks one by one.

Receiving Notifications on Calendar Changes

To create engaging applications with various calendar features, you must learn to receive notifications when calendar items are added, updated, or removed:

1. Define the needed variables:

   /* Watcher identifier */
   var watcherId = 0;
   
   /* This example assumes that the calendar is initialized */
   var calendar;
   

2. Define the event handlers for different notifications using the CalendarChangeCallback listener interface:

   var watcher =
   {
      /* When new items are added */
      onitemsadded: function(items)
      {
         console.log(items.length + " items were added");
      },
   
      /* When items are updated */
      onitemsupdated: function(items)
      {
         console.log(items.length + " items were updated");
      },
   
      /* When items are deleted */
      onitemsremoved: function(ids)
      {
         console.log(ids.length + " items were removed");
      }
   };
   

3. Register the listener to use the defined event handlers:

   watcherId = calendar.addChangeListener(watcher);
   

4. To stop the notifications, use the removeChangeListener() method:

   function cancelWatch()
   {
      calendar.removeChangeListener(watcherId);
   }