<< Click to Display Table of Contents >> Navigation:  »No topics above this level« Google Calendars

NG-ConnectionPack provide access to Google Calendars service, which allows the user to manage it own calendars as well as access to shared common calendars, such as country specific holidays calendars. TNGGCalendars component provide access to Google Calendars service. To use Google Calendars service, please ensure that Calendar API is enabled for your application, registered as described in Google Registration topic:

 

 

Google Calendars service supports several calendars, some of which can be owned (created) by the user, and others can be shared common calendars, provided by other service users or even by other web services in the form of iCalendar standard. NG-ConnectionPack makes no distinctions of whether the calendar is owned by the user or not, except for the primary calendar, which is a user default calendar. TNGGCalendars component just provide access to the list of connected calendars.

 

A calendar contains a set of events, where every event has a lot of attributes, including event text and event dates. Usually, a calendar contains huge amount of events, especially if this is a common shared calendar, such as country specific holidays calendar. So, the application usually should not query all events, but instead should provide scrollable user interface, where events are queried on demand only for specific time interval, such as a week or month.

 

Managing Calendars

 

Individual calendars are represented in NG-ConnectionPack by TNGGCalendar record. The primary, user default calendar can be accessed via Primary property of TNGGCalendars component.

 

Since Google Calendars service supports handling of several calendars, TNGGCalendars component provides Calendars overloaded methods, which allow to retrieve all calendars, accessible to the user:

 

var
  cals: TArray<TNGGCalendar>;
  i:    Integer;
begin
  cals := MyGoogleCals.Calendars;
  for i := 0 to High(cals) do
    Memo1.Lines.Add(cals[i].Summary);
end;

 

As can be seen from above example, Calendars method return an array of TNGGCalendar objects. The second overload version allows to retrieve calendars via inline callback procedure, which in some cases can simplify application's code:

 

MyGoogleCals.Calendars(procedure(C: TNGGCalendar)
begin
  Memo1.Lines.Add(C.Summary);
end);

 

TNGGCalendar provides the following properties:

 

 

Its important to understand, that all these properties are read-only, but the calendar is still can be changed, using TNGGCalendar.TBuilder object, which is returned by the calendar's Update method. The use of builder object is very simple and its allows to update several calendar's properties in a single Http request. Usually, all the method calls chain can be written in code in a single statement like this:

 

var
  cal: TNGGCalendar;
begin
  cal := GetSomeCalendar;
  cal.Update.Summary('My Updated Summary')
            .Description('My Updated Description')
            .Location('My Update Location')
            .Execute;
end;

 

TNGGCalendars component provides Add method to create new calendar. Please note, that the method also returns builder object, and so, should be used as described above:

 

cal := MyCalendars.Add.Summary('My Summary')
                      .Description('My Description')
                      .Execute;

 

A calendar can be deleted using its Delete method:

 

tsk.Delete;

 

TNGGCalendars component also supports ClearPrimary method, which can be used to remove all events from the primary calendar. Google Calendars service does not provide analogous methods for clearing secondary calendars.

 

Managing Calendar Events

 

In NG-ConnectionPack calendar events are represented by TNGGEvent record. As stated above a can calendar contain huge amount of events. So, the application usually should not try to retrieve all events, but instead should provide scrollable user interface, where events are queried on demand only for specific time interval, such as a week or month.

 

NG-ConnectionPack provides an extended API for querying calendar events via TNGGCalendar.TQuery object. In many aspects the use of TQuery object is similar to TBuilder object described above; its returned as a result of Events method of the TNGGCalendar record and the subsequent method call chain can be written in a single statement. for example:

 

var
  cal:   TNGGCalendar;
  evnts: TArray<TNGGEvent>;
begin
  cal   := GetSomeCalendar;
  evnts := cal.Events.TimeMin(Now)
                     .TimeMax(Now + 1)
                     .Execute;
end;

Theere several TQuery methods, which allows to specify different events queries:

 

 

Please note, that Google Calendars service does not support using of any combinations of these query conditions, but some of them can be potentially combined in a single query.

 

TNGGEvent record provides the following properties:

 

 

As with calendars, calendar events also uses corresponding TBuilder object to performs event modification, and as well for adding new events. Adding new event can be done via TNGGCalendar.Add method and modification can be done via event's Update method:

 

var
  cal: TNGGCalendar;
  evt: TNGGevent;
begin
  cal := GetSomeCalendar;
  evt := cal.Add
            .Dates(Now, Now + 1, False)
            .Summary('My Summary')
            .Description('My Description')
            .Execute;
end;

 

TNGGEvent.Delete method can be used to delete en event, if its not Locked:

 

evt.Delete;

 

Event Reminders

 

TNGGEvent.Reminders property provide access to the event reminders. The reminders allows to notify the user just before the event start date-time via e-mail, sms or browser popup window. The application itself it not responsible of implementing one or another reminder behavior. Reminders works inside the service or in your browser (please read Google documentation about setting up browser popup behavior).

 

By default, newly created event use parent calendar's default reminders, and the Reminders.UseDefault property will have a True value. However, the event reminders can be overwritten, using TBuilder.RemindersOverride method, and in that case Reminders.Overrides[] collection property will contain overridden reminders.

 

Except the reminder Method, which can be equal to one of the following values: rmEmail, rmSms, rmPopup, reminder require to specify the time period in Minutes, which determines when the reminder will be executed by the service.

 

Event Colors

 

Google Calendars service provides some UI related features, which is implemented in NG-ConnectionPack only partially. Specifically, NG-ConnectionPack provides access to event color, which is the color that the user can override via NG-ConnectionPack API or in browser interface of Google Calendars service to highlight the event. The user can choose one of the predefined colors, or can leave the event with the default color.

 

The set of color, which can be used is "hard-coded" into Google service, and can be determined via Color[] and ColorCount properties and TryGetColor method of the TNGGCalendars component.

 

Each color is represented by TNGGEventColor record, which provides access to read-only serive provided Id of the color, as well as to Background and Foreground colors.

 

If the event colors was not overridden by the user, its Background and Foreground colors will have clNone value, when reading event colors from the event, using event's Color property. And so, the application should draw the event with its own default colors.