repo_zf1/documentation/manual/de/module_specs/Zend_Gdata_Calendar.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.calendar">
    <title>Google Kalender verwenden</title>
    <para>
        Die <classname>Zend_Gdata_Calendar</classname> Klasse kann verwendet werden um Events im Online Google Kalender
        Service zu sehen, erstellen, updaten und löschen.
    </para>
    <para>
        Siehe
        <ulink url="http://code.google.com/apis/calendar/overview.html">http://code.google.com/apis/calendar/overview.html</ulink>
        für weitere Informationen über die Google Kalender API.
    </para>
    <sect2 id="zend.gdata.calendar.connecting">
        <title>Zum Kalender Service verbinden</title>
        <para>
            Die Google Kalender API basiert, wie alle GData APIs, auf dem Atom Publishing Protocol (APP), einem
            XML basierenden Format für gemanagte Web-basierte Ressourcen. Verkehr zwischen einem Client und den
            Google Kalender Servern läuft über HTTP und erlaubt sowohl authentifizierte als auch unauthentifizierte
            Verbindungen.
        </para>
        <para>
            Bevor irgendeine Transaktion stattfinden kann, muß diese Verbindung erstellt werden. Die Erstellung
            einer Verbindung zu den Kalender Server beinhaltet zwei Schritte: Erstellung eines HTTP Clients und
            das binden einer <classname>Zend_Gdata_Calendar</classname> Instanz an diesen Client.
        </para>
        <sect3 id="zend.gdata.calendar.connecting.authentication">
            <title>Authentifizierung</title>
            <para>
                Die Google Kalender API erlaubt den Zugriff auf beide, öffentliche und private, Kalender Feeds.
                Öfentliche Foods benötigen keine Authentifizierung, aber sie können nur gelesen werden und bieten
                reduzierte Funktionalitäten. Private Feeds bieten die kompletteste Funktionalität benötigen aber
                eine authentifizierte Verbindung zu den Kalender Servern. Es gibt drei Authentifizierungs
                Schemas die von Google Kalender unterstützt werden:
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        <firstterm>ClientAuth</firstterm> bietet direkte Benutzername/Passwort Authentifizierung
                        zu den Kalender Servern. Da dieses Schema erfordert das Benutzer die Anwendung mit Ihrem
                        Passwort versorgen, ist diese Authentifizierung nur zu empfehlen wenn andere
                        Authentifizierungs Schemas nicht anwendbar sind.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>AuthSub</firstterm> erlaubt die Authentifizierung zu den Kalender Servern über
                        einen Google Proxy Server. Das bietet den gleichen Level von Bequemlichkeit wie
                        ClientAuth aber ohne die Sicherheits Risiken, was es zu einer idealen Wahl für Web
                        basierende Anwendungen macht.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>MagicCookie</firstterm> erlaubt die Authentifizierung basieren auf einer
                        semi-zufälligen URL von immerhalb des Google Kalender Interfaces. Das ist das einfachste
                        Authentifizierungs Schema das implmentiert werden kann, erzwingt aber das Benutzer
                        ihre Sicherheits URL manuell empfangen, bevor sie sich authentifizieren können, und ist
                        limitiert auf nur-lesenden Zugriff.
                    </para>
                </listitem>
            </itemizedlist>
            <para>
                Die <classname>Zend_Gdata</classname> Bibliothek bietet Unterstützung für alle drei Authentifizierungs
                Schemas. Der Rest dieses Kapitels nimmt an das die vorhandenen Authentifizierungs Schemas
                geläufig sind und wie eine korrekte Authentifizierte Verbindung erstellt wird. Für weitere Details
                kann in die <link linkend="zend.gdata.introduction.authentication">Authentifizierungs Sektion</link>
                dieses Handbuches, oder in die
                <ulink url="http://code.google.com/apis/gdata/auth.html">Authentifizierungs Übersicht im Google Data API Entwickler Guide</ulink>.
                gesehen werden.
            </para>
        </sect3>
        <sect3 id="zend.gdata.calendar.connecting.service">
            <title>Eine Service Instanz erstellen</title>
            <para>
                Um mit dem Google Kalender zu interagieren, bietet diese Bibliothek die
                <classname>Zend_Gdata_Calendar</classname> Service Klasse. Diese Klasse bietet ein übliches Interface zu den
                Google Data und Atom Publishing Protocol Modellen und assistiert in der Behandlung der Anfragen
                zum und von den Kalender Servern.
            </para>
            <para>
                Sobald ein Authentifizierung Schema ausgewählt wurde, besteht der nächste Schritt darin eine
                Instanz von <classname>Zend_Gdata_Calendar</classname> zu erstellen. Der Klassen Konstruktor nimmt eine
                Instanz von <classname>Zend_Http_Client</classname> als einzelnes Argument. Das bietet ein Interface für
                AuthSub und ClientAuth Authentifizierungen, da beide von Ihnen die Erstellung eines speziellen
                authentifizierten  HTTP Clients benötigen. Wenn keine Argumente angegeben werden, wird
                automatisch eine unauthentifizierte Instanz von <classname>Zend_Http_Client</classname> erstellt.
            </para>
            <para>
                Das folgende Beispiel zeigt wie man eine Kalender Service Klasse erstellt und dabei die
                ClientAuth Authentifizierung verwendet:
            </para>
            <programlisting role="php"><![CDATA[
// Parameter für die ClientAuth Authentifizierung
$service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
$user = "sample.user@gmail.com";
$pass = "pa$$w0rd";

// Erstellt einen authentifizierten HTTP Client
$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);

// Erstellt eine Instanz des Kalender Services
$service = new Zend_Gdata_Calendar($client);
]]></programlisting>
            <para>
                Ein Kalender Service der AuthSub verwendet, kann ähnlich erstellt werden, durch eine etwas längere
                Schreibweise:
            </para>
            <programlisting role="php"><![CDATA[
/*
 * Empfängt die aktuelle URL so das der AuthSub Server weiß wohin er den
 * Benutzer umleiten soll nachdem die Authentifizierung komplett ist.
 */
function getCurrentUrl()
{
    global $_SERVER;

    // Filtert php_self um Sicherheitsprobleme zu vermeiden.
    $php_request_uri =
        htmlentities(substr($_SERVER['REQUEST_URI'],
                            0,
                            strcspn($_SERVER['REQUEST_URI'], "\n\r")),
                            ENT_QUOTES);

    if (isset($_SERVER['HTTPS']) &&
        strtolower($_SERVER['HTTPS']) == 'on') {
        $protocol = 'https://';
    } else {
        $protocol = 'http://';
    }
    $host = $_SERVER['HTTP_HOST'];
    if ($_SERVER['HTTP_PORT'] != '' &&
        (($protocol == 'http://' && $_SERVER['HTTP_PORT'] != '80') ||
        ($protocol == 'https://' && $_SERVER['HTTP_PORT'] != '443'))) {
        $port = ':' . $_SERVER['HTTP_PORT'];
    } else {
        $port = '';
    }
    return $protocol . $host . $port . $php_request_uri;
}

/**
 * Einen AuthSub authentifizierten HTTP Client nehmen, der den Benutzer
 * zum AuthSub Server zum Login umleitet wenn es notwendig ist.
 */
function getAuthSubHttpClient()
{
    global $_SESSION, $_GET;

    // Wenn es keine AuthSub Session oder einmal-benutzbares Token gibt die auf
    // uns warten, den Benutzer zum AuthSub Server umleiten um Ihn zu erhalten
    if (!isset($_SESSION['sessionToken']) && !isset($_GET['token'])) {
        // Parameter für den AuthSub Server
        $next = getCurrentUrl();
        $scope = "http://www.google.com/calendar/feeds/";
        $secure = false;
        $session = true;

        // Den Benutzer zum AuthSub server umleiten zur Anmeldung

        $authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($next,
                                                             $scope,
                                                             $secure,
                                                             $session);
         header("HTTP/1.0 307 Temporary redirect");

         header("Location: " . $authSubUrl);

         exit();
    }

    // Konvertiert ein AuthSub einmal-benutzbares Token in ein Session
    // Token wenn das notwendig ist
    if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
        $_SESSION['sessionToken'] =
            Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
    }

    // An diesem Punkt sind wir authentifiziert über AuthSub und können
    // eine authentifizierte HTTP Client Instanz holen

    // Erstellt einen authentifizierte HTTP Client
    $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
    return $client;
}

// -> Skript Bearbeitung beginnt hier <-

// Sicher stellen das der Benutzer eine gültige Session hat, sodas der
// AuthSub Session Token gespeichert werden kann sobald er vorhanden ist
session_start();

// Erstellt eine Instanz des Kalender Services, und leitet den Benutzer
// zum AuthSub Server um wenn das notwendig ist.
$service = new Zend_Gdata_Calendar(getAuthSubHttpClient());
]]></programlisting>
            <para>
                Schlußendlich, kann ein nicht authentifizierter Server erstellt werden um Ihn entweder mit
                öffentlichen Feeds oder MagicCookie Authentifizierung zu verwenden:</para>
            <programlisting role="php"><![CDATA[
// Erstellt eine Instanz des Kalender Services wobei ein nicht
// authentifizierter HTTP Client verwendet wird

$service = new Zend_Gdata_Calendar();
]]></programlisting>
            <para>
                Es ist zu beachten das die MagicCookie Authentifizierung nicht mit der HTTP Verbindung
                unterstützt wird, sonder stattdessen wärend der gewählten Sichtbarkeit spezifiziert wird,
                wärend Anfragen abgeschickt werden. Siehe die folgende Sektion über das empfangen von Events
                für ein Beispiel.
            </para>
        </sect3>
    </sect2>
    <sect2 id="zend.gdata.calendar_retrieval">
        <title>Eine Kalender Liste empfangen</title>
        <para>
            Der Kalender Service unterstützt den Empfang einer Liste von Kalendern für den authentifizierten
            Benutzer. Das ist die gleiche Liste von Kalendern welche im Google Kalender UI angezeigt werden,
            ausser das jene die als "<code>hidden</code>" markiert sind, auch vorhanden sind.
        </para>
        <para>
            Die Kalender Liste ist immer privat und es muß über eine authentifizierte Verbindung darauf
            zugegriffen werden. Es ist nicht möglich eine Kalender Liste eines anderen Benutzers zu erhalten und
            es kann nicht darauf zugegriffen werden wenn die MagicCookie Authentifizierung verwendet wird.
            Der Versuch auf eine Kalender Liste zuzugreifen ohne das die notwendigen Zugriffsrechte vorhanden
            sind, wird fehlschlagen und in einem 401 (Authentifizierung benötigt) Statuc Code resultieren.
        </para>
        <programlisting role="php"><![CDATA[
$service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$service = new Zend_Gdata_Calendar($client);

try {
    $listFeed= $service->getCalendarListFeed();
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}
]]></programlisting>
        <para>
            Der Aufruf von <code>getCalendarListFeed()</code> erstellt eine neue Instanz von
            <classname>Zend_Gdata_Calendar_ListFeed</classname> die jeden vorhandenen Kalender als Instanz von
            <classname>Zend_Gdata_Calendar_ListEntry</classname> enthält. Nachdem der Feed empfangen wurde, können der
            Iterator und der Accessor die innerhalb des Feeds enthalten sind, verwendet werden um die enthaltenen
            Kalender zu inspizieren.
        </para>
        <programlisting role="php"><![CDATA[
echo "<h1>Kalender Feed Liste</h1>";
echo "<ul>";
foreach ($listFeed as $calendar) {
    echo "<li>" . $calendar->title .
         " (Event Feed: " . $calendar->id . ")</li>";
}
echo "</ul>";
]]></programlisting>
    </sect2>
    <sect2 id="zend.gdata.event_retrieval">
        <title>Events erhalten</title>
        <para>
            Wie die Liste der Kalender können auch die Events empfangen werden durch Verwendung der
            <classname>Zend_Gdata_Calendar</classname> Service Klasse. Die zurückgegebene Event Liste ist vom Typ
            <classname>Zend_Gdata_Calendar_EventFeed</classname> und enthält jedes Event als Instanz von
            <classname>Zend_Gdata_Calendar_EventEntry</classname>. Wie vorher, erlauben die in der Instanz des Event Feeds
            enthaltenen Accessoren und der Iterator das individuelle Events inspiziert werden können.
        </para>
        <sect3 id="zend.gdata.event_retrieval.queries">
            <title>Abfragen</title>
            <para>
                Wenn Events mit der Kalender API empfangen werden, werden speziell erstellte Abfrage URLs verwendet
                um zu beschreiben welche Events zurückgegeben werden sollten. Die
                <classname>Zend_Gdata_Calendar_EventQuery</classname> Klasse vereinfacht diese Aufgabe durch
                automatische Erstellung einer Abfrage URL basierend auf den gegebenen Parametern. Eine komplette
                Liste dieser Parameter ist in der
                <ulink url="http://code.google.com/apis/gdata/reference.html#Queries">Abfrage Sektion des
                Google Data API Protokoll Referenz</ulink> enthalten. Trotzdem gibt es drei Parameter die es
                Wert sind speziell genannt zu werden:
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        <firstterm>User</firstterm> wird verwendet um den Benutzer zu spezifizieren dessen
                        Kalender gesucht wird, und wird als EMail Adresse spezifiziert. Wenn kein Benutzer
                        angegeben wurde, wird stattdessen "default" verwendet um den aktuellen authentifizierten
                        Benutzer anzuzeigen  (wenn er authentifiziert wurde).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Visibility</firstterm> spezifiziert ob der öffentliche oder private Kalender
                        eines Benutzers gesucht werden soll. Wenn eine nicht authentifizierte Session verwendet
                        wird und kein MagicCookie vorhanden ist, ist nur der öffentliche Feed vorhanden.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Projection</firstterm> spezifiziert wieviele Daten vom Server zurückgegeben
                        werden sollen, und in welchem Format. In den meisten Fällen wird man die komplette
                        ("full") Projektion verwenden wollen. Auch die normale ("basic") Projektion ist vorhanden,
                        welche die meisten Meta-Daten in jedem Inhaltsfeld der Events als menschlich lesbaren
                        Text plaziert, und die kombinierte ("composite") Projketion welche den kompletten
                        text für jedes Kommentar entlang jedes Events inkludiert. Die kombinierte ("composite")
                        Ansicht ist oft viel größer als die komplette ("full") Ansicht.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
        <sect3 id="zend.gdata.event_retrieval.start_time">
            <title>Events in der Reihenfolge Ihres Startzeitpunktes erhalten</title>
            <para>
                Das folgende Beispiel zeigt die Verwendung der <classname>Zend_Gdata_Query</classname> Klasse und spezifiziert
                den privat sichtbaren Feed, welcher eine vorhandene authentifizierte Verbindung zu den Kalender
                Servern benötigt. Wenn ein MagicCookie für die Authentifizierung verwendet wird, sollte die
                Sichtbarkeit zuerst auf "<code>private-magicCookieValue</code>" gesetzt werden, sobei
                magicCookieValue der zufälliger String ist, der erhalten wird, wenn man die private XML Adresse
                im Google Kalender UI betrachtet. Events werden chronologisch anhand des Startzeitpunktes angefragt
                und nur Events die in der Zukunft stattfinden werden zurückgegeben.
            </para>
            <programlisting role="php"><![CDATA[
$query = $service->newEventQuery();
$query->setUser('default');
// Setze $query->setVisibility('private-magicCookieValue') wenn
// MagicCookie Authentifizierung verwendet wird
$query->setVisibility('private');
$query->setProjection('full');
$query->setOrderby('starttime');
$query->setFutureevents('true');

// Empfängt die Event Liste vom Kalender Server
try {
    $eventFeed = $service->getCalendarEventFeed($query);
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}

// Iteriere durch die Liste der Events und gib Sie als HTML Liste aus
echo "<ul>";
foreach ($eventFeed as $event) {
    echo "<li>" . $event->title . " (Event ID: " . $event->id . ")</li>";
}
echo "</ul>";
]]></programlisting>
            <para>
                Zusätzliche Eigenschaften wie ID, Autor, Wann, Event Status, Sichtbarkeit, Web Inhalt, und Inhalt,
                sowie andere sind innerhalb von <classname>Zend_Gdata_Calendar_EventEntry</classname> vorhanden. Siehe die
                <ulink url="http://framework.zend.com/apidoc/core/">Zend Framework API Dokumentation</ulink> und
                die <ulink url="http://code.google.com/apis/gdata/reference.html">Lalender Protokol Referenz</ulink>
                für eine komplette Liste.
            </para>
        </sect3>
        <sect3 id="zend.gdata.event_retrieval.date_range">
            <title>Events in einem speziellen Datumsbereich empfangen</title>
            <para>
                Um alle Events in einem gewünschten Bereich auszugeben, zum Beispiel vom 1. Dezember 2006 bis zum
                15. Dezember 2006, müssen die folgenden zwei Zeilen im vorhergehenden Beispiel hinzugefügt werden.
                Es ist zu beachten das "<code>$query->setFutureevents('true')</code>" entfernt werden muß, da
                <code>futureevents</code> die Werte von <code>startMin</code> und <code>startMax</code>
                überschreibt.
            </para>
            <programlisting role="php"><![CDATA[
$query->setStartMin('2006-12-01');
$query->setStartMax('2006-12-16');
]]></programlisting>
            <para>
                Es ist zu beachten das <code>startMin</code> inklusive ist, wobei <code>startMax</code> exklusive
                ist. Als Ergebnis, werden nur die Events bis 2006-12-15 23:59:59 zurückgegeben.
            </para>
        </sect3>
        <sect3 id="zend.gdata.event_retrieval.fulltext">
            <title>Events durch eine Volltext Abfrage erhalten</title>
            <para>
                Um alle Events auszugeben welche ein spezielles Wort, zum Beispiel "Hundefutter" enthalten,
                muß die  <code>setQuery()</code> Methode verwendet werden wenn die Abfrage erstellt wird.
            </para>
            <programlisting role="php"><![CDATA[
$query->setQuery("Hundefutter");
]]></programlisting>
        </sect3>
        <sect3 id="zend.gdata.event_retrieval.individual">
            <title>Individuelle Events erhalten</title>
            <para>
                Individuelle Events können empfangen werden indem deren Event ID als Teil der Abfrage spezifiziert
                wird. Statt <code>getCalendarEventFeed()</code> auszurufen, sollte
                <code>getCalendarEventEntry()</code> aufgerufen werden.
            </para>
            <programlisting role="php"><![CDATA[
$query = $service->newEventQuery();
$query->setUser('default');
$query->setVisibility('private');
$query->setProjection('full');
$query->setEvent($eventId);

try {
    $event = $service->getCalendarEventEntry($query);
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}
]]></programlisting>
            <para>
                In einer ähnlichen Weise kann Sie, wenn die Event URL bekannt ist, direkt an
                <code>getCalendarEntry()</code> übergeben werden um ein spezielles Event zu erhalten. In diesem
                Fall wird kein Abfrage Objekt benötigt da die Event URL alle notwendigen Informationen enthält um
                das Event zu erhalten.
            </para>
            <programlisting role="php"><![CDATA[
$eventURL = "http://www.google.com/calendar/feeds/default/private"
          . "/full/g829on5sq4ag12se91d10uumko";

try {
    $event = $service->getCalendarEventEntry($eventURL);
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}
]]></programlisting>
        </sect3>
    </sect2>
    <sect2 id="zend.gdata.calendar.creating_events">
        <title>Events erstellen</title>
        <sect3 id="zend.gdata.calendar.creating_events.single">
            <title>Ein einmal vorkommendes Event erstellen</title>
            <para>
                Events werden einem Kalender hinzugefügt indem eine Instanz von  <classname>Zend_Gdata_EventEntry</classname>
                erstellt wird, und diese mit den richtigen Daten bekanntgegeben wird. Die Kalender Service Instanz
                (<classname>Zend_Gdata_Calendar</classname>) wird dann verwendet um das Event transparent in XML zu
                konvertieren und diese an den Kalender Server zu senden.
            </para>
            <para>Mindestens die folgenden Attribute sollten gesetzt werden:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <firstterm>Title</firstterm> enthält die Kopfzeile die über jedem Event innerhalb der
                        Google Kalender UI angezeigt wird.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>When</firstterm> zeigt die Dauer des Events und, optional, jede Erinnerung die
                        mit Ihm assoziiert ist. Siehe in die nächste Sektion für mehr Informationen über dieses
                        Attribut.
                    </para>
                </listitem>
            </itemizedlist>
            <para>Andere nützliche Attribute die optional gesetzt werden können sind unter anderem:</para>
            <itemizedlist>
                <listitem>
                    <para>
                        <firstterm>Author</firstterm> liefert Informationen über den Benutzer der das Event
                        erstellt hat.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Content</firstterm> liefert zusätzliche Information über das Event und wird
                        angezeigt wenn die Event Details innerhalb des Google Kalenders angefragt werden.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>EventStatus</firstterm> zeigt an ob ein Event bestätigt, in Wartestellung
                        oder abgebrochen wurde.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Hidden</firstterm> entfernt das Event von der Google Kalender UI.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Transparency</firstterm> zeigt ob das Event Zeit auf der Frei/Belegt Liste
                        des Benutzers benötigt.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>WebContent</firstterm> erlaubt es externe Inhalte zu verlinken und innerhalb
                        eines Events anzubieten.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Where</firstterm> indiziert den Ort des Events.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <firstterm>Visibility</firstterm> erlaubt es das Event vor der öffentlichen Event Liste
                        zu verstecken.
                    </para>
                </listitem>
            </itemizedlist>
            <para>
                Für eine komplette Liste an Event Attributen, kann in die
                <ulink url="http://framework.zend.com/apidoc/core/">Zend Framework API Documentation</ulink> und die
                <ulink url="http://code.google.com/apis/gdata/reference.html">Kalender Protokol Referenz</ulink>
                gesehen werden. Attribute die mehrfache Werte enthalten können, wo wie "where", sind als Arrays
                implementiert und müssen korrekt erstellt werden. Es ist zu beachten das alle diese Attribute
                Objekte als Parameter benötigen. Der Versuch diese stattdessen als Strings oder Primitivvariablen
                bekanntzugeben wird in einem Fehler wärend der Konvertierung in XML führen.
            </para>
            <para>
                Sobald das Event bekanntgegeben wurde, kann es zum Kalender Server hochgeladen werden durch
                seine Übergabe als Argument zur <code>insertEvent()</code> Funktion des Kalender Services.
            </para>
            <programlisting role="php"><![CDATA[
// Erstellt einen neuen Eintrag und verwendet die magische Factory
// Methode vom Kalender Service
$event= $service->newEventEntry();

// Gibt das Event bekannt mit den gewünschten Informationen
// Beachte das jedes Attribu als Instanz der zugehörenden Klasse erstellt wird
$event->title = $service->newTitle("Mein Event");
$event->where = array($service->newWhere("Berg Ansicht, Kalifornien"));
$event->content =
    $service->newContent(" Das ist mein super Event. RSVP benötigt.");

// Setze das Datum und verwende das RFC 3339 Format.
$startDate = "2008-01-20";
$startTime = "14:00";
$endDate = "2008-01-20";
$endTime = "16:00";
$tzOffset = "-08";

$when = $service->newWhen();
$when->startTime = "{$startDate}T{$startTime}:00.000{$tzOffset}:00";
$when->endTime = "{$endDate}T{$endTime}:00.000{$tzOffset}:00";
$event->when = array($when);

// Das Event an den Kalender Server hochladen
// Eine Kopie des Events wird zurückgegeben wenn es am Server gespeichert wird
$newEvent = $service->insertEvent($event);
]]></programlisting>
        </sect3>
        <sect3 id="zend.gdata.calendar.creating_events.schedulers_reminders">
            <title>Event Planungen und Erinnerungen</title>
            <para>
                Die Startzeit und Dauer eines Events werden durch die Werte seiner <code>when</code> Eigenschaften,
                <code>startTime</code>, <code>endTime</code>, und <code>valueString</code> ermittelt.
                <code>startTime</code> und <code>endTime</code> kontrollieren die Dauer des Events, wärend die
                <code>valueString</code> Eigenschaft aktuell nicht verwendet wird.
            </para>
            <para>
                Jeden Tag wiederkehrende Events können geplant werden indem nur das Datum spezifiziert und
                die Zeit ausgelassen wird wenn <code>startTime</code> und <code>endTime</code> gesetzt werden.
                Genauso können Events die keine Dauer haben spezifiziert werden indem <code>endTime</code>
                unterdrückt wird. In allen Fällen sollten Datums und Zeitwerte im
                <ulink url="http://www.ietf.org/rfc/rfc3339.txt">RFC3339</ulink> Format angegeben werden.
            </para>
            <programlisting role="php"><![CDATA[
// Plane ein Event das am 05. Dezember 2007 um 14h PST stattfindet
// (UTC-8) mit der Dauer einer Stunde.
$when = $service->newWhen();
$when->startTime = "2007-12-05T14:00:00-08:00";
$when->endTime="2007-12-05T15:00:00:00-08:00";

// Die "when" Eigenschaft an das Event binden
$event->when = array($when);
]]></programlisting>
            <para>
                Das <code>when</code> Attribut kontrolliert auch wann Erinnerungen an einen Benutzer gesendet
                werden. Erinnerungen werden in einem Array gespeichert und jedes Event kann abgefragt werden
                um die Erinnerungen herauszufinden die mit Ihm verbunden sind.
            </para>
            <para>
                Damit ein <code>reminder</code> gültig ist, muß er zwei Attribute gesetzt haben: <code>method</code>
                und eine Zeit. <code>Method</code> akzeptiert einen der folgenden Strings: "alert", "email" oder
                "sms". Die Zeit sollte als Integer eingegeben werden und kann mit den Eigenschaften
                <code>minutes</code>, <code>hours</code>, <code>days</code> oder <code>absoluteTime</code>
                gesetzt werden. Trotzdem darf eine gültige Anfrage nur eines dieser Attribute gesetzt haben.
                Wenn eine gemischte Zeit gewünscht wird, muß der Wert in die am besten passende und vorhandene
                Einheit konvertiert werden. Zum Beispiel, 1 Stunde und 30 Minuten sollten als 90 Minuten angegeben
                werden.
            </para>
            <programlisting role="php"><![CDATA[
// Erstellt ein Erinnerungs Objekt. Es sollte eine Email an den Benutzer
// senden, 10 Minuten vor dem Event.
$reminder = $service->newReminder();
$reminder->method = "email";
$reminder->minutes = "10";

// Die Erinnerung einem existierenden Event als "when" Eigenschaft hinzufügen
$when = $event->when[0];
$when->reminders = array($reminder);
]]></programlisting>
        </sect3>
        <sect3 id="zend.gdata.calendar.creating_events.recurring">
            <title>Wiederkehrende Events erstellen</title>
            <para>
                Wiederkehrende Events werden auf dem gleichen Weg erstellt wie einmal stattfindende Events,
                ausser das ein Wiederholungs "recurrence" Attribut statt dem "where" Attribut angegeben werden
                muß. Das Wiederholungs Attribut sollte einen String enthalten der das Wiederholungs Pattern des
                Events beschreibt und das mit Eigenschaften definiert werden kann die im iCalender Standard
                (<ulink url="http://www.ietf.org/rfc/rfc2445.txt">RFC 2445</ulink>) beschrieben sind.
            </para>
            <para>
                Ausnahmen im Wiederholungs Pattern werden normalerweise durch ein ausgeprägtes
                <code>recurrenceException</code> Attribut spezifiziert. Trotzdem bietet der iCalender Standard
                ein zweites Format für die Definition von Wiederholungen, und die Möglichkeit das jedes von Ihnen
                verwendet werden kann und für jedes davon muß das gehandhabt werden.
            </para>
            <para>
                Durch die Komplexität des analysierens des Wiederholungs Patterns, sind weitere Informationen
                hierüber ausserhalb des Umfangs dieses Dokuments. Trotzdem können weitere Informationen im
                <ulink url="http://code.google.com/apis/gdata/elements.html#gdRecurrence">Kapitel über normale
                Elemente des Google Data API Entwickler Leitfadens</ulink> gefunden werden, sowie in der
                RFC 2445.
            </para>
            <programlisting role="php"><![CDATA[
// Erstelle einen neuen Eintrag und verwendet die magische
// Factory Methode des Kalender Services
$event= $service->newEventEntry();

// Gibt das Event mit den gewünschten Informationen bekannt
// Es ist zu beachten das jedes Attribut als Instanz
// der betreffenden Klasse erstellt wird
$event->title = $service->newTitle("Mein wiederkehrendes Event");
$event->where = array($service->newWhere("Palo Alto, Kalifornien"));
$event->content =
    $service->newContent('Das ist mein anderes super Event, ' .
                         'das jeden Dienstag von 01.05.2007 bis ' .
                         '04.09.2007 stattfinden. Kein RSVP benötigt.");

// Setzt Dauer und Frequenz durch Spezifizierung des Wiederholungs Patterns

$recurrence = "DTSTART;VALUE=DATE:20070501\r\n" .
        "DTEND;VALUE=DATE:20070502\r\n" .
        "RRULE:FREQ=WEEKLY;BYDAY=Tu;UNTIL=20070904\r\n";

$event->recurrence = $service->newRecurrence($recurrence);

// Das Event zum Kalender Server hochladen
// Eine Kopie des Events wird zurückgegeben,
// wenn es auf dem Server gespeichert wird
$newEvent = $service->insertEvent($event);
]]></programlisting>
        </sect3>
        <sect3 id="zend.gdata.calendar.creating_events.quickadd">
            <title>QuickAdd verwenden</title>
            <para>
                QuickAdd ist ein Feature das es erlaubt Events zu erstellen indem ein frei definierter Texteintrag
                verwendet wird. Zum Beispie lwürde der String "Abendessen bei Joe's Dinner am Dienstag" ein
                Event erstellen mit dem Titel "Abendessen", dem Ort "Joe's Dinner", und dem Datum "Dienstag".
                Um die Vorteile von QuickAdd zu verwenden, muß eine neue <code>QuickAdd</code> Eigenschaft erstellt,
                auf "true" gesetzt und der frei definierbare Text als <code>content</code> Eigenschaft
                gespeichert werden.
            </para>
            <programlisting role="php"><![CDATA[
 // Erstelle einen neuen Eintrag und verwendet die magische
 // Factory Methode des Kalender Services
$event= $service->newEventEntry();

// Gibt das Event mit den gewünschten Informationen bekannt
$event->content= $service->newContent("Dinner at Joe's Diner on Thursday");
$event->quickAdd = $service->newQuickAdd("true");

// Das Event zum Kalender Server hochladen
// Eine Kopie des Events wird zurückgegeben,
// wenn es auf dem Server gespeichert wird
$newEvent = $service->insertEvent($event);
]]></programlisting>
        </sect3>
    </sect2>
    <sect2 id="zend.gdata.calendar.modifying_events">
        <title>Events bearbeiten</title>
        <para>
            Sobald eine Instanz eines Events erstellt wurde, können die Attribute des Events lokal auf dem selben
            Weg wie bei der Erstellung des Events geänder werden. Sobald alle Änderungen komplett sind, schickt
            der Aufruf der <code>save()</code> Methode des Events die Änderungen an den Kalender Server und gibt
            eine Kopie des Events zurück wie es auf dem Server erstellt wurde.
        </para>
        <para>
            Im Fall das ein anderer Benutzer das Event modifiziert hat seitdem die lokale Kopie empfangen wurde,
            wird die <code>save()</code> Methode fehlschlagen und einen 409 (Konflikt) Status Code zurück geben.
            Um das zu beheben muß eine neue Kopie des Events vom Server empfangen werden bevor ein erneuter
            Versuch stattfindet die Änderungen wieder zu speichern.
        </para>
        <programlisting role="php"><![CDATA[
// Das erste Event auf der Liste der Events eines Benutzers erhalten
$event = $eventFeed[0];

// Den Titel zu einem neuen Wert ändern
$event->title = $service->newTitle("Wuff!");

// Die Änderungen an den Server hochladen
try {
    $event->save();
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}
]]></programlisting>
    </sect2>
    <sect2 id="zend.gdata.calendar.deleting_events">
        <title>Events löschen</title>
        <para>
            Kalender Events können entweder durch den Aufruf der <code>delete()</code> Methode des Kalender
            Services, und des Angebens der Bearbeitungs URL des Events durchgeführt werden, oder durch
            Aufruf der eigenen <code>delete()</code> Methode des Events.
        </para>
        <para>
            In jedem Fall, wird das gelöschte Event trotzdem noch am Privaten Event Feed des Benutzers
            aufscheinen wenn ein <code>updateMin</code> Abfrage Parameter angegeben wurde. Gelöschte Events
            können von normalen Events unterschieden werden weil Sie Ihre eigene <code>eventStatus</code>
            Eigenschaft auf "http://schemas.google.com/g/2005#event.canceled" gesetzt haben.
        </para>
        <programlisting role="php"><![CDATA[
// Option 1: Events können direkt gelöscht werden
$event->delete();
]]></programlisting>
        <programlisting role="php"><![CDATA[
// Option 2: Events können gelöscht werden indem die Bearbeitungs URL
// des Events zu diesem Kalender Service angegeben wird, wenn diese
// bekannt ist
$service->delete($event->getEditLink()->href);
]]></programlisting>
    </sect2>
    <sect2 id="zend.gdata.calendar.comments">
        <title>Auf Event Kommentare zugreifen</title>
        <para>
            Den die komplette Event Ansicht verwendet wird, werden Kommentare nicht direkt innerhalb eines Events
            gespeichert. Stattdessen enthält jedes Event eine URL zum dazugehörigen Kommentar Feed welcher
            manuell angefragt werden muß.
        </para>
        <para>
            Das Arbeiten mit Kommentaren ist fundamental ähnlich zum Arbeiten mit Events, mit dem einzigen
            signifikanten Unterschied das eine andere Feed und Event Klasse verwendet werden sollte, und das
            die zusätzlichen Meta-Daten für Events wie zum Beispiel "where" und "when" für Kommentare nicht
            existieren. Speziell wird der Author des Kommentars in der <code>author</code> Eigenschaft und der
            Kommentar Text in der <code>content</code> Eigenschaft gespeichert.
        </para>
        <programlisting role="php"><![CDATA[
// Die normale URL vom ersten Event der Feed Liste des Benutzers extrahieren
$event = $eventFeed[0];
$commentUrl = $event->comments->feedLink->url;

// Die Kommentarliste für das Event erhalten
try {
$commentFeed = $service->getFeed($commentUrl);
} catch (Zend_Gdata_App_Exception $e) {
    echo "Fehler: " . $e->getMessage();
}

// Jedes Kommentar als HTML Liste ausgeben
echo "<ul>";
foreach ($commentFeed as $comment) {
    echo "<li><em>Kommentar von: " . $comment->author->name "</em><br/>" .
         $comment->content . "</li>";
}
echo "</ul>";
]]></programlisting>
    </sect2>
</sect1>