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 "<code>hidden</code>" 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                 "<code>private-magicCookieValue</code>", where magicCookieValue is the random
 372                 string obtained when viewing the private <acronym>XML</acronym> address in the
 373                 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 "<code>$query->setFutureevents('true')</code>", since
 420                 <code>futureevents</code> will override <code>startMin</code> and
 421                 <code>startMax</code>.
 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 <code>startMin</code> is inclusive whereas <code>startMax</code> is
 431                 exclusive. As a result, only events through 2006-12-15 23:59:59 will be returned.
 432             </para>
 433         </sect3>
 434
 435         <sect3 id="zend.gdata.event_retrieval.fulltext">
 436             <title>Retrieving Events By Fulltext Query</title>
 437
 438             <para>
 439                 To print out all events which contain a specific word, for example "dogfood", use
 440                 the <methodname>setQuery()</methodname> method when creating the query.
 441             </para>
 442
 443             <programlisting language="php"><![CDATA[
 444 $query->setQuery("dogfood");
 445 ]]></programlisting>
 446         </sect3>
 447
 448         <sect3 id="zend.gdata.event_retrieval.individual">
 449             <title>Retrieving Individual Events</title>
 450
 451             <para>
 452                 Individual events can be retrieved by specifying their event ID as part of the
 453                 query. Instead of calling <methodname>getCalendarEventFeed()</methodname>,
 454                 <methodname>getCalendarEventEntry()</methodname> should be called instead.
 455             </para>
 456
 457             <programlisting language="php"><![CDATA[
 458 $query = $service->newEventQuery();
 459 $query->setUser('default');
 460 $query->setVisibility('private');
 461 $query->setProjection('full');
 462 $query->setEvent($eventId);
 463
 464 try {
 465     $event = $service->getCalendarEventEntry($query);
 466 } catch (Zend_Gdata_App_Exception $e) {
 467     echo "Error: " . $e->getMessage();
 468 }
 469 ]]></programlisting>
 470
 471             <para>
 472                 In a similar fashion, if the event <acronym>URL</acronym> is known, it can be passed
 473                 directly into <methodname>getCalendarEntry()</methodname> to retrieve a specific
 474                 event. In this case, no query object is required since the event
 475                 <acronym>URL</acronym> contains all the necessary information to retrieve the event.
 476             </para>
 477
 478             <programlisting language="php"><![CDATA[
 479 $eventURL = "http://www.google.com/calendar/feeds/default/private"
 480           . "/full/g829on5sq4ag12se91d10uumko";
 481
 482 try {
 483     $event = $service->getCalendarEventEntry($eventURL);
 484 } catch (Zend_Gdata_App_Exception $e) {
 485     echo "Error: " . $e->getMessage();
 486 }
 487 ]]></programlisting>
 488         </sect3>
 489     </sect2>
 490
 491     <sect2 id="zend.gdata.calendar.creating_events">
 492         <title>Creating Events</title>
 493
 494         <sect3 id="zend.gdata.calendar.creating_events.single">
 495             <title>Creating Single-Occurrence Events</title>
 496
 497             <para>
 498                 Events are added to a calendar by creating an instance of
 499                 <classname>Zend_Gdata_EventEntry</classname> and populating it with the appropriate
 500                 data. The calendar service instance (<classname>Zend_Gdata_Calendar</classname>) is
 501                 then used to used to transparently covert the event into <acronym>XML</acronym> and
 502                 POST it to the calendar server. Creating events requires either an AuthSub or
 503                 ClientAuth authenticated connection to the calendar server.
 504             </para>
 505
 506             <para>At a minimum, the following attributes should be set:</para>
 507
 508             <itemizedlist>
 509                 <listitem>
 510                     <para>
 511                         <firstterm>Title</firstterm>
 512                         provides the headline that will appear above the event
 513                         within the Google Calendar UI.
 514                     </para>
 515                 </listitem>
 516
 517                 <listitem>
 518                     <para>
 519                         <firstterm>When</firstterm>
 520                         indicates the duration of the event and, optionally,
 521                         any reminders that are associated with it. See the next
 522                         section for more information on this attribute.
 523                     </para>
 524                 </listitem>
 525             </itemizedlist>
 526
 527             <para>Other useful attributes that may optionally set include:</para>
 528
 529             <itemizedlist>
 530                 <listitem>
 531                     <para>
 532                         <firstterm>Author</firstterm>
 533                         provides information about the user who created the
 534                         event.
 535                     </para>
 536                 </listitem>
 537
 538                 <listitem>
 539                     <para>
 540                         <firstterm>Content</firstterm>
 541                         provides additional information about the event which
 542                         appears when the event details are requested from
 543                         within Google Calendar.
 544                     </para>
 545                 </listitem>
 546
 547                 <listitem>
 548                     <para>
 549                         <firstterm>EventStatus</firstterm>
 550                         indicates whether the event is confirmed, tentative, or
 551                         canceled.
 552                     </para>
 553                 </listitem>
 554
 555                 <listitem>
 556                     <para>
 557                         <firstterm>Hidden</firstterm>
 558                         removes the event from the Google Calendar UI.
 559                     </para>
 560                 </listitem>
 561
 562                 <listitem>
 563                     <para>
 564                         <firstterm>Transparency</firstterm>
 565                         indicates whether the event should be consume time on
 566                         the user's free/busy list.
 567                     </para>
 568                 </listitem>
 569
 570                 <listitem>
 571                     <para>
 572                         <firstterm>WebContent</firstterm>
 573                         allows links to external content to be provided within
 574                         an event.
 575                     </para>
 576                 </listitem>
 577
 578                 <listitem>
 579                     <para>
 580                         <firstterm>Where</firstterm>
 581                         indicates the location of the event.
 582                     </para>
 583                 </listitem>
 584
 585                 <listitem>
 586                     <para>
 587                         <firstterm>Visibility</firstterm>
 588                         allows the event to be hidden from the public event
 589                         lists.
 590                     </para>
 591                 </listitem>
 592             </itemizedlist>
 593
 594             <para>
 595                 For a complete list of event attributes, refer to the <ulink
 596                     url="http://framework.zend.com/apidoc/core/">Zend Framework
 597                     <acronym>API</acronym> Documentation</ulink> and the <ulink
 598                     url="http://code.google.com/apis/gdata/reference.html">Calendar Protocol
 599                     Reference</ulink>. Attributes that can contain multiple values, such as where,
 600                 are implemented as arrays and need to be created accordingly. Be aware that all of
 601                 these attributes require objects as parameters. Trying instead to populate them
 602                 using strings or primitives will result in errors during conversion to
 603                 <acronym>XML</acronym>.
 604             </para>
 605
 606             <para>
 607                 Once the event has been populated, it can be uploaded to the calendar server by
 608                 passing it as an argument to the calendar service's
 609                 <methodname>insertEvent()</methodname> function.
 610             </para>
 611
 612             <programlisting language="php"><![CDATA[
 613 // Create a new entry using the calendar service's magic factory method
 614 $event= $service->newEventEntry();
 615
 616 // Populate the event with the desired information
 617 // Note that each attribute is crated as an instance of a matching class
 618 $event->title = $service->newTitle("My Event");
 619 $event->where = array($service->newWhere("Mountain View, California"));
 620 $event->content =
 621     $service->newContent(" This is my awesome event. RSVP required.");
 622
 623 // Set the date using RFC 3339 format.
 624 $startDate = "2008-01-20";
 625 $startTime = "14:00";
 626 $endDate = "2008-01-20";
 627 $endTime = "16:00";
 628 $tzOffset = "-08";
 629
 630 $when = $service->newWhen();
 631 $when->startTime = "{$startDate}T{$startTime}:00.000{$tzOffset}:00";
 632 $when->endTime = "{$endDate}T{$endTime}:00.000{$tzOffset}:00";
 633 $event->when = array($when);
 634
 635 // Upload the event to the calendar server
 636 // A copy of the event as it is recorded on the server is returned
 637 $newEvent = $service->insertEvent($event);
 638 ]]></programlisting>
 639         </sect3>
 640
 641         <sect3 id="zend.gdata.calendar.creating_events.schedulers_reminders">
 642             <title>Event Schedules and Reminders</title>
 643
 644             <para>
 645                 An event's starting time and duration are determined by the value of its
 646                 <code>when</code> property, which contains the properties
 647                 <code>startTime</code>, <code>endTime</code>, and <code>valueString</code>.
 648                 <code>StartTime</code> and <code>EndTime</code> control the duration of the
 649                 event, while the <code>valueString</code> property is currently unused.
 650             </para>
 651
 652             <para>
 653                 All-day events can be scheduled by specifying only the date omitting the time when
 654                 setting <code>startTime</code> and <code>endTime</code>. Likewise, zero-duration
 655                 events can be specified by omitting the <code>endTime</code>. In all cases,
 656                 date/time values should be provided in
 657                 <ulink url="http://www.ietf.org/rfc/rfc3339.txt">RFC3339</ulink> format.
 658             </para>
 659
 660             <programlisting language="php"><![CDATA[
 661 // Schedule the event to occur on December 05, 2007 at 2 PM PST (UTC-8)
 662 // with a duration of one hour.
 663 $when = $service->newWhen();
 664 $when->startTime = "2007-12-05T14:00:00-08:00";
 665 $when->endTime="2007-12-05T15:00:00:00-08:00";
 666
 667 // Apply the when property to an event
 668 $event->when = array($when);
 669 ]]></programlisting>
 670
 671             <para>
 672                 The <code>when</code> attribute also controls when reminders are sent to a user.
 673                 Reminders are stored in an array and each event may have up to find reminders
 674                 associated with it.
 675             </para>
 676
 677             <para>
 678                 For a <code>reminder</code> to be valid, it needs to have two attributes set:
 679                 <code>method</code> and a time. <code>Method</code> can accept one of the following
 680                 strings: "alert", "email", or "sms". The time should be entered as an integer and
 681                 can be set with either the property <code>minutes</code>, <code>hours</code>,
 682                 <code>days</code>, or <code>absoluteTime</code>. However, a valid request may only
 683                 have one of these attributes set. If a mixed time is desired, convert to the most
 684                 precise unit available. For example, 1 hour and 30 minutes should be entered as 90
 685                 minutes.
 686             </para>
 687
 688             <programlisting language="php"><![CDATA[
 689 // Create a new reminder object. It should be set to send an email
 690 // to the user 10 minutes beforehand.
 691 $reminder = $service->newReminder();
 692 $reminder->method = "email";
 693 $reminder->minutes = "10";
 694
 695 // Apply the reminder to an existing event's when property
 696 $when = $event->when[0];
 697 $when->reminders = array($reminder);
 698 ]]></programlisting>
 699         </sect3>
 700
 701         <sect3 id="zend.gdata.calendar.creating_events.recurring">
 702             <title>Creating Recurring Events</title>
 703
 704             <para>
 705                 Recurring events are created the same way as single-occurrence events, except a
 706                 recurrence attribute should be provided instead of a where attribute. The
 707                 recurrence attribute should hold a string describing the event's recurrence pattern
 708                 using properties defined in the iCalendar standard (<ulink
 709                 url="http://www.ietf.org/rfc/rfc2445.txt">RFC 2445</ulink>).
 710             </para>
 711
 712             <para>
 713                 Exceptions to the recurrence pattern will usually be specified by a distinct
 714                 <code>recurrenceException</code> attribute. However, the iCalendar standard
 715                 provides a secondary format for defining recurrences, and the possibility that
 716                 either may be used must be accounted for.
 717             </para>
 718
 719             <para>
 720                 Due to the complexity of parsing recurrence patterns, further information on this
 721                 them is outside the scope of this document. However, more information can be found
 722                 in the <ulink
 723                     url="http://code.google.com/apis/gdata/elements.html#gdRecurrence">Common
 724                     Elements section of the Google Data <acronym>API</acronym>s Developer
 725                     Guide</ulink>, as well as in <acronym>RFC</acronym> 2445.
 726             </para>
 727
 728             <programlisting language="php"><![CDATA[
 729  // Create a new entry using the calendar service's magic factory method
 730 $event= $service->newEventEntry();
 731
 732 // Populate the event with the desired information
 733 // Note that each attribute is crated as an instance of a matching class
 734 $event->title = $service->newTitle("My Recurring Event");
 735 $event->where = array($service->newWhere("Palo Alto, California"));
 736 $event->content =
 737     $service->newContent(' This is my other awesome event, ' .
 738                          ' occurring all-day every Tuesday from .
 739                          '2007-05-01 until 207-09-04. No RSVP required.');
 740
 741 // Set the duration and frequency by specifying a recurrence pattern.
 742
 743 $recurrence = "DTSTART;VALUE=DATE:20070501\r\n" .
 744         "DTEND;VALUE=DATE:20070502\r\n" .
 745         "RRULE:FREQ=WEEKLY;BYDAY=Tu;UNTIL=20070904\r\n";
 746
 747 $event->recurrence = $service->newRecurrence($recurrence);
 748
 749 // Upload the event to the calendar server
 750 // A copy of the event as it is recorded on the server is returned
 751 $newEvent = $service->insertEvent($event);
 752 ]]></programlisting>
 753         </sect3>
 754
 755         <sect3 id="zend.gdata.calendar.creating_events.quickadd">
 756             <title>Using QuickAdd</title>
 757
 758             <para>
 759                 QuickAdd is a feature which allows events to be created using free-form text entry.
 760                 For example, the string "Dinner at Joe's Diner on Thursday" would create an event
 761                 with the title "Dinner", location "Joe's Diner", and date "Thursday". To take
 762                 advantage of QuickAdd, create a new <code>QuickAdd</code> property set to
 763                 <constant>TRUE</constant> and store the freeform text as a <code>content</code>
 764                 property.
 765             </para>
 766
 767             <programlisting language="php"><![CDATA[
 768 // Create a new entry using the calendar service's magic factory method
 769 $event= $service->newEventEntry();
 770
 771 // Populate the event with the desired information
 772 $event->content= $service->newContent("Dinner at Joe's Diner on Thursday");
 773 $event->quickAdd = $service->newQuickAdd("true");
 774
 775 // Upload the event to the calendar server
 776 // A copy of the event as it is recorded on the server is returned
 777 $newEvent = $service->insertEvent($event);
 778 ]]></programlisting>
 779         </sect3>
 780     </sect2>
 781
 782     <sect2 id="zend.gdata.calendar.modifying_events">
 783         <title>Modifying Events</title>
 784
 785         <para>
 786             Once an instance of an event has been obtained, the event's attributes can be locally
 787             modified in the same way as when creating an event. Once all modifications are
 788             complete, calling the event's <methodname>save()</methodname> method will upload the
 789             changes to the calendar server and return a copy of the event as it was created on the
 790             server.
 791         </para>
 792
 793         <para>
 794             In the event another user has modified the event since the local copy was retrieved,
 795             <methodname>save()</methodname> will fail and the server will return a 409 (Conflict)
 796             status code. To resolve this a fresh copy of the event must be retrieved from the server
 797             before attempting to resubmit any modifications.
 798         </para>
 799
 800         <programlisting language="php"><![CDATA[
 801 // Get the first event in the user's event list
 802 $event = $eventFeed[0];
 803
 804 // Change the title to a new value
 805 $event->title = $service->newTitle("Woof!");
 806
 807 // Upload the changes to the server
 808 try {
 809     $event->save();
 810 } catch (Zend_Gdata_App_Exception $e) {
 811     echo "Error: " . $e->getMessage();
 812 }
 813 ]]></programlisting>
 814     </sect2>
 815
 816     <sect2 id="zend.gdata.calendar.deleting_events">
 817         <title>Deleting Events</title>
 818
 819         <para>
 820             Calendar events can be deleted either by calling the calendar service's
 821             <methodname>delete()</methodname> method and providing the edit <acronym>URL</acronym>
 822             of an event or by calling an existing event's own <methodname>delete()</methodname>
 823             method.
 824         </para>
 825
 826         <para>
 827             In either case, the deleted event will still show up on a user's private event feed if
 828             an <code>updateMin</code> query parameter is provided. Deleted events can be
 829             distinguished from regular events because they will have their <code>eventStatus</code>
 830             property set to "http://schemas.google.com/g/2005#event.canceled".
 831         </para>
 832
 833         <programlisting language="php"><![CDATA[
 834 // Option 1: Events can be deleted directly
 835 $event->delete();
 836 ]]></programlisting>
 837
 838         <programlisting language="php"><![CDATA[
 839 // Option 2: Events can be deleted supplying the edit URL of the event
 840 // to the calendar service, if known
 841 $service->delete($event->getEditLink()->href);
 842 ]]></programlisting>
 843     </sect2>
 844
 845     <sect2 id="zend.gdata.calendar.comments">
 846         <title>Accessing Event Comments</title>
 847
 848         <para>
 849             When using the full event view, comments are not directly stored within an entry.
 850             Instead, each event contains a <acronym>URL</acronym> to its associated comment feed
 851             which must be manually requested.
 852         </para>
 853
 854         <para>
 855             Working with comments is fundamentally similar to working with events, with the only
 856             significant difference being that a different feed and event class should be used and
 857             that the additional meta-data for events such as where and when does not exist for
 858             comments. Specifically, the comment's author is stored in the <code>author</code>
 859             property, and the comment text is stored in the <code>content</code> property.
 860         </para>
 861
 862         <programlisting language="php"><![CDATA[
 863 // Extract the comment URL from the first event in a user's feed list
 864 $event = $eventFeed[0];
 865 $commentUrl = $event->comments->feedLink->url;
 866
 867 // Retrieve the comment list for the event
 868 try {
 869 $commentFeed = $service->getFeed($commentUrl);
 870 } catch (Zend_Gdata_App_Exception $e) {
 871     echo "Error: " . $e->getMessage();
 872 }
 873
 874 // Output each comment as an HTML list
 875 echo "<ul>";
 876 foreach ($commentFeed as $comment) {
 877     echo "<li><em>Comment By: " . $comment->author->name "</em><br/>" .
 878          $comment->content . "</li>";
 879 }
 880 echo "</ul>";
 881 ]]></programlisting>
 882     </sect2>
 883 </sect1>