documentation/manual/en/module_specs/Zend_Gdata_Calendar.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.calendar">
   4     <title>Using Google Calendar</title>
   5
   6     <para>
   7         You can use the
   8         <classname>Zend_Gdata_Calendar</classname>
   9         class to view, create, update, and delete events in the online Google Calendar service.
  10     </para>
  11
  12     <para>
  13         See <ulink
  14         url="http://code.google.com/apis/calendar/overview.html">
  15         http://code.google.com/apis/calendar/overview.html</ulink>
  16         for more information about the Google Calendar <acronym>API</acronym>.
  17     </para>
  18
  19     <sect2 id="zend.gdata.calendar.connecting">
  20         <title>Connecting To The Calendar Service</title>
  21
  22         <para>
  23             The Google Calendar <acronym>API</acronym>, like all GData <acronym>API</acronym>s, is
  24             based off of the Atom Publishing Protocol (APP), an <acronym>XML</acronym> based format
  25             for managing web-based resources. Traffic between a client and the Google Calendar
  26             servers occurs over <acronym>HTTP</acronym> and allows for both authenticated and
  27             unauthenticated connections.
  28         </para>
  29
  30         <para>
  31             Before any transactions can occur, this connection needs to be made. Creating a
  32             connection to the calendar servers involves two steps: creating an
  33             <acronym>HTTP</acronym> client and binding a <classname>Zend_Gdata_Calendar</classname>
  34             service instance to that client.
  35         </para>
  36
  37         <sect3 id="zend.gdata.calendar.connecting.authentication">
  38             <title>Authentication</title>
  39
  40             <para>
  41                 The Google Calendar <acronym>API</acronym> allows access to both public and private
  42                 calendar feeds. Public feeds do not require authentication, but are read-only and
  43                 offer reduced functionality. Private feeds offers the most complete functionality
  44                 but requires an authenticated connection to the calendar servers. There are three
  45                 authentication schemes that are supported by Google Calendar:
  46             </para>
  47
  48             <itemizedlist>
  49                 <listitem>
  50                     <para>
  51                         <firstterm>ClientAuth</firstterm>
  52                         provides direct username/password authentication to the
  53                         calendar servers. Since this scheme requires that users
  54                         provide your application with their password, this
  55                         authentication is only recommended when other
  56                         authentication schemes are insufficient.
  57                     </para>
  58                 </listitem>
  59
  60                 <listitem>
  61                     <para>
  62                         <firstterm>AuthSub</firstterm>
  63                         allows authentication to the calendar servers via a
  64                         Google proxy server. This provides the same level of
  65                         convenience as ClientAuth but without the security
  66                         risk, making this an ideal choice for web-based
  67                         applications.
  68                     </para>
  69                 </listitem>
  70
  71                 <listitem>
  72                     <para>
  73                         <firstterm>MagicCookie</firstterm>
  74                         allows authentication based on a semi-random <acronym>URL</acronym>
  75                         available from within the Google Calendar interface.
  76                         This is the simplest authentication scheme to
  77                         implement, but requires that users manually retrieve
  78                         their secure <acronym>URL</acronym> before they can authenticate, doesn't
  79                         provide access to calendar lists, and is limited to
  80                         read-only access.
  81                     </para>
  82                 </listitem>
  83             </itemizedlist>
  84
  85             <para>
  86                 The <classname>Zend_Gdata</classname>
  87                 library provides support for all three authentication schemes.
  88                 The rest of this chapter will assume that you are familiar the
  89                 authentication schemes available and how to create an
  90                 appropriate authenticated connection. For more information,
  91                 please see section the <link
  92                 linkend="zend.gdata.introduction.authentication">Authentication section</link>
  93                 of this manual or the <ulink
  94                 url="http://code.google.com/apis/gdata/auth.html">Authentication Overview in the
  95                 Google Data <acronym>API</acronym> Developer's Guide</ulink>.
  96             </para>
  97         </sect3>
  98
  99         <sect3 id="zend.gdata.calendar.connecting.service">
 100             <title>Creating A Service Instance</title>
 101
 102             <para>
 103                 In order to interact with Google Calendar, this library provides the
 104                 <classname>Zend_Gdata_Calendar</classname> service class. This class provides a
 105                 common interface to the Google Data and Atom Publishing Protocol models and assists
 106                 in marshaling requests to and from the calendar servers.
 107             </para>
 108
 109             <para>
 110                 Once deciding on an authentication scheme, the next step is to create an instance
 111                 of <classname>Zend_Gdata_Calendar</classname>. The class constructor takes an
 112                 instance of <classname>Zend_Http_Client</classname> as a single argument. This
 113                 provides an interface for AuthSub and ClientAuth authentication, as both of these
 114                 require creation of a special authenticated <acronym>HTTP</acronym> client. If no
 115                 arguments are provided, an unauthenticated instance of
 116                 <classname>Zend_Http_Client</classname> will be automatically created.
 117             </para>
 118
 119             <para>
 120                 The example below shows how to create a Calendar service class using ClientAuth
 121                 authentication:
 122             </para>
 123
 124             <programlisting language="php"><![CDATA[
 125 // Parameters for ClientAuth authentication
 126 $service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
 127 $user = "sample.user@gmail.com";
 128 $pass = "pa$$w0rd";
 129
 130 // Create an authenticated HTTP client
 131 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 132
 133 // Create an instance of the Calendar service
 134 $service = new Zend_Gdata_Calendar($client);
 135 ]]></programlisting>
 136
 137             <para>
 138                 A Calendar service using AuthSub can be created in a similar, though slightly more
 139                 lengthy fashion:
 140             </para>
 141
 142             <programlisting language="php"><![CDATA[
 143 /*
 144  * Retrieve the current URL so that the AuthSub server knows where to
 145  * redirect the user after authentication is complete.
 146  */
 147 function getCurrentUrl()
 148 {
 149     global $_SERVER;
 150
 151     // Filter php_self to avoid a security vulnerability.
 152     $php_request_uri =
 153         htmlentities(substr($_SERVER['REQUEST_URI'],
 154                             0,
 155                             strcspn($_SERVER['REQUEST_URI'], "\n\r")),
 156                             ENT_QUOTES);
 157
 158     if (isset($_SERVER['HTTPS']) &&
 159         strtolower($_SERVER['HTTPS']) == 'on') {
 160         $protocol = 'https://';
 161     } else {
 162         $protocol = 'http://';
 163     }
 164     $host = $_SERVER['HTTP_HOST'];
 165     if ($_SERVER['HTTP_PORT'] != '' &&
 166         (($protocol == 'http://' && $_SERVER['HTTP_PORT'] != '80') ||
 167         ($protocol == 'https://' && $_SERVER['HTTP_PORT'] != '443'))) {
 168         $port = ':' . $_SERVER['HTTP_PORT'];
 169     } else {
 170         $port = '';
 171     }
 172     return $protocol . $host . $port . $php_request_uri;
 173 }
 174
 175 /**
 176  * Obtain an AuthSub authenticated HTTP client, redirecting the user
 177  * to the AuthSub server to login if necessary.
 178  */
 179 function getAuthSubHttpClient()
 180 {
 181     global $_SESSION, $_GET;
 182
 183     // if there is no AuthSub session or one-time token waiting for us,
 184     // redirect the user to the AuthSub server to get one.
 185     if (!isset($_SESSION['sessionToken']) && !isset($_GET['token'])) {
 186         // Parameters to give to AuthSub server
 187         $next = getCurrentUrl();
 188         $scope = "http://www.google.com/calendar/feeds/";
 189         $secure = false;
 190         $session = true;
 191
 192         // Redirect the user to the AuthSub server to sign in
 193
 194         $authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($next,
 195                                                              $scope,
 196                                                              $secure,
 197                                                              $session);
 198          header("HTTP/1.0 307 Temporary redirect");
 199
 200          header("Location: " . $authSubUrl);
 201
 202          exit();
 203     }
 204
 205     // Convert an AuthSub one-time token into a session token if needed
 206     if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
 207         $_SESSION['sessionToken'] =
 208             Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
 209     }
 210
 211     // At this point we are authenticated via AuthSub and can obtain an
 212     // authenticated HTTP client instance
 213
 214     // Create an authenticated HTTP client
 215     $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
 216     return $client;
 217 }
 218
 219 // -> Script execution begins here <-
 220
 221 // Make sure that the user has a valid session, so we can record the
 222 // AuthSub session token once it is available.
 223 session_start();
 224
 225 // Create an instance of the Calendar service, redirecting the user
 226 // to the AuthSub server if necessary.
 227 $service = new Zend_Gdata_Calendar(getAuthSubHttpClient());
 228 ]]></programlisting>
 229
 230             <para>
 231                 Finally, an unauthenticated server can be created for use with either public feeds
 232                 or MagicCookie authentication:
 233             </para>
 234
 235             <programlisting language="php"><![CDATA[
 236 // Create an instance of the Calendar service using an unauthenticated
 237 // HTTP client
 238
 239 $service = new Zend_Gdata_Calendar();
 240 ]]></programlisting>
 241
 242             <para>
 243                 Note that MagicCookie authentication is not supplied with the
 244                 <acronym>HTTP</acronym> connection, but is instead specified along with the desired
 245                 visibility when submitting queries. See the section on retrieving events below for
 246                 an example.
 247             </para>
 248         </sect3>
 249     </sect2>
 250
 251     <sect2 id="zend.gdata.calendar_retrieval">
 252         <title>Retrieving A Calendar List</title>
 253
 254         <para>
 255             The calendar service supports retrieving a list of calendars for the authenticated
 256             user. This is the same list of calendars which are displayed in the Google Calendar
 257             UI, except those marked as "<emphasis>hidden</emphasis>" are also available.
 258         </para>
 259
 260         <para>
 261             The calendar list is always private and must be accessed over an authenticated
 262             connection. It is not possible to retrieve another user's calendar list and it cannot
 263             be accessed using MagicCookie authentication. Attempting to access a calendar list
 264             without holding appropriate credentials will fail and result in a 401 (Authentication
 265             Required) status code.
 266         </para>
 267
 268         <programlisting language="php"><![CDATA[
 269 $service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
 270 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 271 $service = new Zend_Gdata_Calendar($client);
 272
 273 try {
 274     $listFeed= $service->getCalendarListFeed();
 275 } catch (Zend_Gdata_App_Exception $e) {
 276     echo "Error: " . $e->getMessage();
 277 }
 278 ]]></programlisting>
 279
 280         <para>
 281             Calling <methodname>getCalendarListFeed()</methodname> creates a new instance of
 282             <classname>Zend_Gdata_Calendar_ListFeed</classname> containing each available calendar
 283             as an instance of <classname>Zend_Gdata_Calendar_ListEntry</classname>. After retrieving
 284             the feed, you can use the iterator and accessors contained within the feed to inspect
 285             the enclosed calendars.
 286         </para>
 287
 288         <programlisting language="php"><![CDATA[
 289 echo "<h1>Calendar List Feed</h1>";
 290 echo "<ul>";
 291 foreach ($listFeed as $calendar) {
 292     echo "<li>" . $calendar->title .
 293          " (Event Feed: " . $calendar->id . ")</li>";
 294 }
 295 echo "</ul>";
 296 ]]></programlisting>
 297     </sect2>
 298
 299     <sect2 id="zend.gdata.event_retrieval">
 300         <title>Retrieving Events</title>
 301
 302         <para>
 303             Like the list of calendars, events are also retrieved using the
 304             <classname>Zend_Gdata_Calendar</classname> service class. The event list returned is of
 305             type <classname>Zend_Gdata_Calendar_EventFeed</classname> and contains each event as an
 306             instance of <classname>Zend_Gdata_Calendar_EventEntry</classname>. As before, the
 307             iterator and accessors contained within the event feed instance allow inspection of
 308             individual events.
 309         </para>
 310
 311         <sect3 id="zend.gdata.event_retrieval.queries">
 312             <title>Queries</title>
 313
 314             <para>
 315                 When retrieving events using the Calendar <acronym>API</acronym>, specially
 316                 constructed query <acronym>URL</acronym>s are used to describe what events should be
 317                 returned. The <classname>Zend_Gdata_Calendar_EventQuery</classname> class simplifies
 318                 this task by automatically constructing a query <acronym>URL</acronym> based on
 319                 provided parameters. A full list of these parameters is available at the <ulink
 320                     url="http://code.google.com/apis/gdata/reference.html#Queries">Queries section
 321                     of the Google Data <acronym>API</acronym>s Protocol Reference</ulink>. However,
 322                 there are three parameters that are worth special attention:
 323             </para>
 324
 325             <itemizedlist>
 326                 <listitem>
 327                     <para>
 328                         <firstterm>User</firstterm>
 329                         is used to specify the user whose calendar is being
 330                         searched for, and is specified as an email address. If
 331                         no user is provided, "default" will be used instead to
 332                         indicate the currently authenticated user (if
 333                         authenticated).
 334                     </para>
 335                 </listitem>
 336
 337                 <listitem>
 338                     <para>
 339                         <firstterm>Visibility</firstterm>
 340                         specifies whether a users public or private calendar
 341                         should be searched. If using an unauthenticated session
 342                         and no MagicCookie is available, only the public feed
 343                         will be available.
 344                     </para>
 345                 </listitem>
 346
 347                 <listitem>
 348                     <para>
 349                         <firstterm>Projection</firstterm>
 350                         specifies how much data should be returned by the
 351                         server and in what format. In most cases you will want
 352                         to use the "full" projection. Also available is the
 353                         "basic" projection, which places most meta-data into
 354                         each event's content field as human readable text, and
 355                         the "composite" projection which includes complete text
 356                         for any comments alongside each event. The "composite"
 357                         view is often much larger than the "full" view.
 358                     </para>
 359                 </listitem>
 360             </itemizedlist>
 361         </sect3>
 362
 363         <sect3 id="zend.gdata.event_retrieval.start_time">
 364             <title>Retrieving Events In Order Of Start Time</title>
 365
 366             <para>
 367                 The example below illustrates the use of the <classname>Zend_Gdata_Query</classname>
 368                 class and specifies the private visibility feed, which requires that an
 369                 authenticated connection is available to the calendar servers. If a MagicCookie is
 370                 being used for authentication, the visibility should be instead set to
 371                 "<emphasis>private-magicCookieValue</emphasis>", where magicCookieValue is the
 372                 random string obtained when viewing the private <acronym>XML</acronym> address in
 373                 the Google Calendar UI. Events are requested chronologically by start time and only
 374                 events occurring in the future are returned.
 375             </para>
 376
 377             <programlisting language="php"><![CDATA[
 378 $query = $service->newEventQuery();
 379 $query->setUser('default');
 380 // Set to $query->setVisibility('private-magicCookieValue') if using
 381 // MagicCookie auth
 382 $query->setVisibility('private');
 383 $query->setProjection('full');
 384 $query->setOrderby('starttime');
 385 $query->setFutureevents('true');
 386
 387 // Retrieve the event list from the calendar server
 388 try {
 389     $eventFeed = $service->getCalendarEventFeed($query);
 390 } catch (Zend_Gdata_App_Exception $e) {
 391     echo "Error: " . $e->getMessage();
 392 }
 393
 394 // Iterate through the list of events, outputting them as an HTML list
 395 echo "<ul>";
 396 foreach ($eventFeed as $event) {
 397     echo "<li>" . $event->title . " (Event ID: " . $event->id . ")</li>";
 398 }
 399 echo "</ul>";
 400 ]]></programlisting>
 401
 402             <para>
 403                 Additional properties such as ID, author, when, event status, visibility, web
 404                 content, and content, among others are available within
 405                 <classname>Zend_Gdata_Calendar_EventEntry</classname>. Refer to the
 406                 <ulink url="http://framework.zend.com/apidoc/core/">Zend Framework
 407                 <acronym>API</acronym> Documentation</ulink> and the
 408                 <ulink url="http://code.google.com/apis/gdata/reference.html">Calendar Protocol
 409                 Reference</ulink> for a complete list.
 410             </para>
 411         </sect3>
 412
 413         <sect3 id="zend.gdata.event_retrieval.date_range">
 414             <title>Retrieving Events In A Specified Date Range</title>
 415
 416             <para>
 417                 To print out all events within a certain range, for example from December 1,
 418                 2006 through December 15, 2007, add the following two lines to the previous sample.
 419                 Take care to remove "<command>$query->setFutureevents('true')</command>", since
 420                 <property>futureevents</property> will override <property>startMin</property> and
 421                 <property>startMax</property>.
 422             </para>
 423
 424             <programlisting language="php"><![CDATA[
 425 $query->setStartMin('2006-12-01');
 426 $query->setStartMax('2006-12-16');
 427 ]]></programlisting>
 428
 429             <para>
 430                 Note that <property>startMin</property> is inclusive whereas
 431                 <property>startMax</property> is exclusive. As a result, only events through
 432                 2006-12-15 23:59:59 will be returned.
 433             </para>
 434         </sect3>
 435
 436         <sect3 id="zend.gdata.event_retrieval.fulltext">
 437             <title>Retrieving Events By Fulltext Query</title>
 438
 439             <para>
 440                 To print out all events which contain a specific word, for example "dogfood", use
 441                 the <methodname>setQuery()</methodname> method when creating the query.
 442             </para>
 443
 444             <programlisting language="php"><![CDATA[
 445 $query->setQuery("dogfood");
 446 ]]></programlisting>
 447         </sect3>
 448
 449         <sect3 id="zend.gdata.event_retrieval.individual">
 450             <title>Retrieving Individual Events</title>
 451
 452             <para>
 453                 Individual events can be retrieved by specifying their event ID as part of the
 454                 query. Instead of calling <methodname>getCalendarEventFeed()</methodname>,
 455                 <methodname>getCalendarEventEntry()</methodname> should be called instead.
 456             </para>
 457
 458             <programlisting language="php"><![CDATA[
 459 $query = $service->newEventQuery();
 460 $query->setUser('default');
 461 $query->setVisibility('private');
 462 $query->setProjection('full');
 463 $query->setEvent($eventId);
 464
 465 try {
 466     $event = $service->getCalendarEventEntry($query);
 467 } catch (Zend_Gdata_App_Exception $e) {
 468     echo "Error: " . $e->getMessage();
 469 }
 470 ]]></programlisting>
 471
 472             <para>
 473                 In a similar fashion, if the event <acronym>URL</acronym> is known, it can be passed
 474                 directly into <methodname>getCalendarEntry()</methodname> to retrieve a specific
 475                 event. In this case, no query object is required since the event
 476                 <acronym>URL</acronym> contains all the necessary information to retrieve the event.
 477             </para>
 478
 479             <programlisting language="php"><![CDATA[
 480 $eventURL = "http://www.google.com/calendar/feeds/default/private"
 481           . "/full/g829on5sq4ag12se91d10uumko";
 482
 483 try {
 484     $event = $service->getCalendarEventEntry($eventURL);
 485 } catch (Zend_Gdata_App_Exception $e) {
 486     echo "Error: " . $e->getMessage();
 487 }
 488 ]]></programlisting>
 489         </sect3>
 490     </sect2>
 491
 492     <sect2 id="zend.gdata.calendar.creating_events">
 493         <title>Creating Events</title>
 494
 495         <sect3 id="zend.gdata.calendar.creating_events.single">
 496             <title>Creating Single-Occurrence Events</title>
 497
 498             <para>
 499                 Events are added to a calendar by creating an instance of
 500                 <classname>Zend_Gdata_EventEntry</classname> and populating it with the appropriate
 501                 data. The calendar service instance (<classname>Zend_Gdata_Calendar</classname>) is
 502                 then used to used to transparently covert the event into <acronym>XML</acronym> and
 503                 POST it to the calendar server. Creating events requires either an AuthSub or
 504                 ClientAuth authenticated connection to the calendar server.
 505             </para>
 506
 507             <para>At a minimum, the following attributes should be set:</para>
 508
 509             <itemizedlist>
 510                 <listitem>
 511                     <para>
 512                         <firstterm>Title</firstterm>
 513                         provides the headline that will appear above the event
 514                         within the Google Calendar UI.
 515                     </para>
 516                 </listitem>
 517
 518                 <listitem>
 519                     <para>
 520                         <firstterm>When</firstterm>
 521                         indicates the duration of the event and, optionally,
 522                         any reminders that are associated with it. See the next
 523                         section for more information on this attribute.
 524                     </para>
 525                 </listitem>
 526             </itemizedlist>
 527
 528             <para>Other useful attributes that may optionally set include:</para>
 529
 530             <itemizedlist>
 531                 <listitem>
 532                     <para>
 533                         <firstterm>Author</firstterm>
 534                         provides information about the user who created the
 535                         event.
 536                     </para>
 537                 </listitem>
 538
 539                 <listitem>
 540                     <para>
 541                         <firstterm>Content</firstterm>
 542                         provides additional information about the event which
 543                         appears when the event details are requested from
 544                         within Google Calendar.
 545                     </para>
 546                 </listitem>
 547
 548                 <listitem>
 549                     <para>
 550                         <firstterm>EventStatus</firstterm>
 551                         indicates whether the event is confirmed, tentative, or
 552                         canceled.
 553                     </para>
 554                 </listitem>
 555
 556                 <listitem>
 557                     <para>
 558                         <firstterm>Hidden</firstterm>
 559                         removes the event from the Google Calendar UI.
 560                     </para>
 561                 </listitem>
 562
 563                 <listitem>
 564                     <para>
 565                         <firstterm>Transparency</firstterm>
 566                         indicates whether the event should be consume time on
 567                         the user's free/busy list.
 568                     </para>
 569                 </listitem>
 570
 571                 <listitem>
 572                     <para>
 573                         <firstterm>WebContent</firstterm>
 574                         allows links to external content to be provided within
 575                         an event.
 576                     </para>
 577                 </listitem>
 578
 579                 <listitem>
 580                     <para>
 581                         <firstterm>Where</firstterm>
 582                         indicates the location of the event.
 583                     </para>
 584                 </listitem>
 585
 586                 <listitem>
 587                     <para>
 588                         <firstterm>Visibility</firstterm>
 589                         allows the event to be hidden from the public event
 590                         lists.
 591                     </para>
 592                 </listitem>
 593             </itemizedlist>
 594
 595             <para>
 596                 For a complete list of event attributes, refer to the <ulink
 597                     url="http://framework.zend.com/apidoc/core/">Zend Framework
 598                     <acronym>API</acronym> Documentation</ulink> and the <ulink
 599                     url="http://code.google.com/apis/gdata/reference.html">Calendar Protocol
 600                     Reference</ulink>. Attributes that can contain multiple values, such as where,
 601                 are implemented as arrays and need to be created accordingly. Be aware that all of
 602                 these attributes require objects as parameters. Trying instead to populate them
 603                 using strings or primitives will result in errors during conversion to
 604                 <acronym>XML</acronym>.
 605             </para>
 606
 607             <para>
 608                 Once the event has been populated, it can be uploaded to the calendar server by
 609                 passing it as an argument to the calendar service's
 610                 <methodname>insertEvent()</methodname> function.
 611             </para>
 612
 613             <programlisting language="php"><![CDATA[
 614 // Create a new entry using the calendar service's magic factory method
 615 $event= $service->newEventEntry();
 616
 617 // Populate the event with the desired information
 618 // Note that each attribute is crated as an instance of a matching class
 619 $event->title = $service->newTitle("My Event");
 620 $event->where = array($service->newWhere("Mountain View, California"));
 621 $event->content =
 622     $service->newContent(" This is my awesome event. RSVP required.");
 623
 624 // Set the date using RFC 3339 format.
 625 $startDate = "2008-01-20";
 626 $startTime = "14:00";
 627 $endDate = "2008-01-20";
 628 $endTime = "16:00";
 629 $tzOffset = "-08";
 630
 631 $when = $service->newWhen();
 632 $when->startTime = "{$startDate}T{$startTime}:00.000{$tzOffset}:00";
 633 $when->endTime = "{$endDate}T{$endTime}:00.000{$tzOffset}:00";
 634 $event->when = array($when);
 635
 636 // Upload the event to the calendar server
 637 // A copy of the event as it is recorded on the server is returned
 638 $newEvent = $service->insertEvent($event);
 639 ]]></programlisting>
 640         </sect3>
 641
 642         <sect3 id="zend.gdata.calendar.creating_events.schedulers_reminders">
 643             <title>Event Schedules and Reminders</title>
 644
 645             <para>
 646                 An event's starting time and duration are determined by the value of its
 647                 <property>when</property> property, which contains the properties
 648                 <property>startTime</property>, <property>endTime</property>, and
 649                 <property>valueString</property>. <emphasis>StartTime</emphasis> and
 650                 <emphasis>EndTime</emphasis> control the duration of the
 651                 event, while the <property>valueString</property> property is currently unused.
 652             </para>
 653
 654             <para>
 655                 All-day events can be scheduled by specifying only the date omitting the time when
 656                 setting <property>startTime</property> and <property>endTime</property>. Likewise,
 657                 zero-duration events can be specified by omitting the <property>endTime</property>.
 658                 In all cases, date and time values should be provided in
 659                 <ulink url="http://www.ietf.org/rfc/rfc3339.txt">RFC3339</ulink> format.
 660             </para>
 661
 662             <programlisting language="php"><![CDATA[
 663 // Schedule the event to occur on December 05, 2007 at 2 PM PST (UTC-8)
 664 // with a duration of one hour.
 665 $when = $service->newWhen();
 666 $when->startTime = "2007-12-05T14:00:00-08:00";
 667 $when->endTime="2007-12-05T15:00:00:00-08:00";
 668
 669 // Apply the when property to an event
 670 $event->when = array($when);
 671 ]]></programlisting>
 672
 673             <para>
 674                 The <property>when</property> attribute also controls when reminders are sent to a
 675                 user. Reminders are stored in an array and each event may have up to find reminders
 676                 associated with it.
 677             </para>
 678
 679             <para>
 680                 For a <emphasis>reminder</emphasis> to be valid, it needs to have two attributes
 681                 set: <property>method</property> and a time. <emphasis>Method</emphasis> can accept
 682                 one of the following strings: "alert", "email", or "sms". The time should be entered
 683                 as an integer and can be set with either the property <property>minutes</property>,
 684                 <property>hours</property>, <property>days</property>, or
 685                 <property>absoluteTime</property>. However, a valid request may only have one of
 686                 these attributes set. If a mixed time is desired, convert to the most precise unit
 687                 available. For example, 1 hour and 30 minutes should be entered as 90 minutes.
 688             </para>
 689
 690             <programlisting language="php"><![CDATA[
 691 // Create a new reminder object. It should be set to send an email
 692 // to the user 10 minutes beforehand.
 693 $reminder = $service->newReminder();
 694 $reminder->method = "email";
 695 $reminder->minutes = "10";
 696
 697 // Apply the reminder to an existing event's when property
 698 $when = $event->when[0];
 699 $when->reminders = array($reminder);
 700 ]]></programlisting>
 701         </sect3>
 702
 703         <sect3 id="zend.gdata.calendar.creating_events.recurring">
 704             <title>Creating Recurring Events</title>
 705
 706             <para>
 707                 Recurring events are created the same way as single-occurrence events, except a
 708                 recurrence attribute should be provided instead of a where attribute. The
 709                 recurrence attribute should hold a string describing the event's recurrence pattern
 710                 using properties defined in the iCalendar standard (<ulink
 711                 url="http://www.ietf.org/rfc/rfc2445.txt">RFC 2445</ulink>).
 712             </para>
 713
 714             <para>
 715                 Exceptions to the recurrence pattern will usually be specified by a distinct
 716                 <property>recurrenceException</property> attribute. However, the iCalendar standard
 717                 provides a secondary format for defining recurrences, and the possibility that
 718                 either may be used must be accounted for.
 719             </para>
 720
 721             <para>
 722                 Due to the complexity of parsing recurrence patterns, further information on this
 723                 them is outside the scope of this document. However, more information can be found
 724                 in the <ulink
 725                     url="http://code.google.com/apis/gdata/elements.html#gdRecurrence">Common
 726                     Elements section of the Google Data <acronym>API</acronym>s Developer
 727                     Guide</ulink>, as well as in <acronym>RFC</acronym> 2445.
 728             </para>
 729
 730             <programlisting language="php"><![CDATA[
 731  // Create a new entry using the calendar service's magic factory method
 732 $event= $service->newEventEntry();
 733
 734 // Populate the event with the desired information
 735 // Note that each attribute is crated as an instance of a matching class
 736 $event->title = $service->newTitle("My Recurring Event");
 737 $event->where = array($service->newWhere("Palo Alto, California"));
 738 $event->content =
 739     $service->newContent(' This is my other awesome event, ' .
 740                          ' occurring all-day every Tuesday from .
 741                          '2007-05-01 until 207-09-04. No RSVP required.');
 742
 743 // Set the duration and frequency by specifying a recurrence pattern.
 744
 745 $recurrence = "DTSTART;VALUE=DATE:20070501\r\n" .
 746         "DTEND;VALUE=DATE:20070502\r\n" .
 747         "RRULE:FREQ=WEEKLY;BYDAY=Tu;UNTIL=20070904\r\n";
 748
 749 $event->recurrence = $service->newRecurrence($recurrence);
 750
 751 // Upload the event to the calendar server
 752 // A copy of the event as it is recorded on the server is returned
 753 $newEvent = $service->insertEvent($event);
 754 ]]></programlisting>
 755         </sect3>
 756
 757         <sect3 id="zend.gdata.calendar.creating_events.quickadd">
 758             <title>Using QuickAdd</title>
 759
 760             <para>
 761                 QuickAdd is a feature which allows events to be created using free-form text entry.
 762                 For example, the string "Dinner at Joe's Diner on Thursday" would create an event
 763                 with the title "Dinner", location "Joe's Diner", and date "Thursday". To take
 764                 advantage of QuickAdd, create a new <property>QuickAdd</property> property set to
 765                 <constant>TRUE</constant> and store the freeform text as a
 766                 <property>content</property> property.
 767             </para>
 768
 769             <programlisting language="php"><![CDATA[
 770 // Create a new entry using the calendar service's magic factory method
 771 $event= $service->newEventEntry();
 772
 773 // Populate the event with the desired information
 774 $event->content= $service->newContent("Dinner at Joe's Diner on Thursday");
 775 $event->quickAdd = $service->newQuickAdd("true");
 776
 777 // Upload the event to the calendar server
 778 // A copy of the event as it is recorded on the server is returned
 779 $newEvent = $service->insertEvent($event);
 780 ]]></programlisting>
 781         </sect3>
 782     </sect2>
 783
 784     <sect2 id="zend.gdata.calendar.modifying_events">
 785         <title>Modifying Events</title>
 786
 787         <para>
 788             Once an instance of an event has been obtained, the event's attributes can be locally
 789             modified in the same way as when creating an event. Once all modifications are
 790             complete, calling the event's <methodname>save()</methodname> method will upload the
 791             changes to the calendar server and return a copy of the event as it was created on the
 792             server.
 793         </para>
 794
 795         <para>
 796             In the event another user has modified the event since the local copy was retrieved,
 797             <methodname>save()</methodname> will fail and the server will return a 409 (Conflict)
 798             status code. To resolve this a fresh copy of the event must be retrieved from the server
 799             before attempting to resubmit any modifications.
 800         </para>
 801
 802         <programlisting language="php"><![CDATA[
 803 // Get the first event in the user's event list
 804 $event = $eventFeed[0];
 805
 806 // Change the title to a new value
 807 $event->title = $service->newTitle("Woof!");
 808
 809 // Upload the changes to the server
 810 try {
 811     $event->save();
 812 } catch (Zend_Gdata_App_Exception $e) {
 813     echo "Error: " . $e->getMessage();
 814 }
 815 ]]></programlisting>
 816     </sect2>
 817
 818     <sect2 id="zend.gdata.calendar.deleting_events">
 819         <title>Deleting Events</title>
 820
 821         <para>
 822             Calendar events can be deleted either by calling the calendar service's
 823             <methodname>delete()</methodname> method and providing the edit <acronym>URL</acronym>
 824             of an event or by calling an existing event's own <methodname>delete()</methodname>
 825             method.
 826         </para>
 827
 828         <para>
 829             In either case, the deleted event will still show up on a user's private event feed if
 830             an <property>updateMin</property> query parameter is provided. Deleted events can be
 831             distinguished from regular events because they will have their
 832             <property>eventStatus</property> property set to
 833             "http://schemas.google.com/g/2005#event.canceled".
 834         </para>
 835
 836         <programlisting language="php"><![CDATA[
 837 // Option 1: Events can be deleted directly
 838 $event->delete();
 839 ]]></programlisting>
 840
 841         <programlisting language="php"><![CDATA[
 842 // Option 2: Events can be deleted supplying the edit URL of the event
 843 // to the calendar service, if known
 844 $service->delete($event->getEditLink()->href);
 845 ]]></programlisting>
 846     </sect2>
 847
 848     <sect2 id="zend.gdata.calendar.comments">
 849         <title>Accessing Event Comments</title>
 850
 851         <para>
 852             When using the full event view, comments are not directly stored within an entry.
 853             Instead, each event contains a <acronym>URL</acronym> to its associated comment feed
 854             which must be manually requested.
 855         </para>
 856
 857         <para>
 858             Working with comments is fundamentally similar to working with events, with the only
 859             significant difference being that a different feed and event class should be used and
 860             that the additional meta-data for events such as where and when does not exist for
 861             comments. Specifically, the comment's author is stored in the
 862             <property>author</property> property, and the comment text is stored in the
 863             <property>content</property> property.
 864         </para>
 865
 866         <programlisting language="php"><![CDATA[
 867 // Extract the comment URL from the first event in a user's feed list
 868 $event = $eventFeed[0];
 869 $commentUrl = $event->comments->feedLink->url;
 870
 871 // Retrieve the comment list for the event
 872 try {
 873 $commentFeed = $service->getFeed($commentUrl);
 874 } catch (Zend_Gdata_App_Exception $e) {
 875     echo "Error: " . $e->getMessage();
 876 }
 877
 878 // Output each comment as an HTML list
 879 echo "<ul>";
 880 foreach ($commentFeed as $comment) {
 881     echo "<li><em>Comment By: " . $comment->author->name "</em><br/>" .
 882          $comment->content . "</li>";
 883 }
 884 echo "</ul>";
 885 ]]></programlisting>
 886     </sect2>
 887 </sect1>