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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 22068 -->
<!-- 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 <acronym>API</acronym>.
    </para>

    <sect2 id="zend.gdata.calendar.connecting">
        <title>Zum Kalender Service verbinden</title>

        <para>
            Die Google Kalender <acronym>API</acronym> basiert, wie alle GData
            <acronym>API</acronym>s, auf dem Atom Publishing Protocol (APP), einem
            <acronym>XML</acronym> basierenden Format für gemanagte Web-basierte Ressourcen. Verkehr
            zwischen einem Client und den Google Kalender Servern läuft über <acronym>HTTP</acronym>
            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 <acronym>HTTP</acronym> 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 <acronym>API</acronym> erlaubt den Zugriff auf beide,
                öffentliche und private, Kalender Feeds. Öffentliche Feeds 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 <acronym>URL</acronym> von immerhalb des
                        Google Kalender Interfaces. Das ist das einfachste Authentifizierungs Schema
                        das implmentiert werden kann, erzwingt aber das Benutzer ihre Sicherheits
                        <acronym>URL</acronym> 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 <acronym>API</acronym> 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 <acronym>HTTP</acronym> 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 language="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 language="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 language="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
                <acronym>HTTP</acronym> Verbindung unterstützt wird, sondern stattdessen während der
                gewählten Sichtbarkeit spezifiziert wird, während 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 "<emphasis>hidden</emphasis>"
            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 language="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 <methodname>getCalendarListFeed()</methodname> 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 language="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 <acronym>API</acronym> empfangen werden, werden
                speziell erstellte Abfrage <acronym>URL</acronym>s 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 <acronym>URL</acronym> 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 <acronym>API</acronym> 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 "<emphasis>private-magicCookieValue</emphasis>"
                gesetzt werden, sobei magicCookieValue der zufälliger String ist, der erhalten wird,
                wenn man die private <acronym>XML</acronym> 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 language="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
                    <acronym>API</acronym> 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
                "<command>$query->setFutureevents('true')</command>" entfernt werden muß, da
                <property>futureevents</property> die Werte von <property>startMin</property> und
                <property>startMax</property> überschreibt.
            </para>

            <programlisting language="php"><![CDATA[
$query->setStartMin('2006-12-01');
$query->setStartMax('2006-12-16');
]]></programlisting>

            <para>
                Es ist zu beachten das <property>startMin</property> inklusive ist, wobei
                <property>startMax</property> 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 <methodname>setQuery()</methodname> Methode verwendet werden wenn
                die Abfrage erstellt wird.
            </para>

            <programlisting language="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 <methodname>getCalendarEventFeed()</methodname>
                auszurufen, sollte <methodname>getCalendarEventEntry()</methodname> aufgerufen
                werden.
            </para>

            <programlisting language="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 <acronym>URL</acronym> bekannt
                ist, direkt an <methodname>getCalendarEntry()</methodname> übergeben werden um ein
                spezielles Event zu erhalten. In diesem Fall wird kein Abfrage Objekt benötigt da
                die Event <acronym>URL</acronym> alle notwendigen Informationen enthält um das Event
                zu erhalten.
            </para>

            <programlisting language="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 <acronym>XML</acronym> 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
                    <acronym>API</acronym> 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ährend der Konvertierung in <acronym>XML</acronym> führen.
            </para>

            <para>
                Sobald das Event bekanntgegeben wurde, kann es zum Kalender Server hochgeladen
                werden durch seine Übergabe als Argument zur <methodname>insertEvent()</methodname>
                Funktion des Kalender Services.
            </para>

            <programlisting language="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
                <property>when</property> Eigenschaften, <property>startTime</property>,
                <property>endTime</property>, und <property>valueString</property> ermittelt.
                <emphasis>StartTime</emphasis> und <emphasis>EndTime</emphasis>
                kontrollieren die Dauer des Events, während die <property>valueString</property>
                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 <property>startTime</property> und
                <property>endTime</property> gesetzt werden. Genauso können Events die keine Dauer
                haben spezifiziert werden indem <property>endTime</property> 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 language="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 <property>when</property> 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 <emphasis>reminder</emphasis> gültig ist, muß er zwei Attribute gesetzt
                haben: <property>method</property> und eine Zeit. <emphasis>Method</emphasis>
                akzeptiert einen der folgenden Strings: "alert", "email" oder "sms". Die Zeit sollte
                als Integer eingegeben werden und kann mit den Eigenschaften
                <property>minutes</property>, <property>hours</property>, <property>days</property>
                oder <property>absoluteTime</property> 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 language="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
                <property>recurrenceException</property> 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 <acronym>API</acronym> Entwickler
                    Leitfadens</ulink> gefunden werden, sowie in der <acronym>RFC</acronym> 2445.
            </para>

            <programlisting language="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 <property>QuickAdd</property> Eigenschaft erstellt, auf
                <constant>TRUE</constant> gesetzt und der frei definierbare Text als
                <property>content</property> Eigenschaft gespeichert werden.
            </para>

            <programlisting language="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 <methodname>save()</methodname> 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 <methodname>save()</methodname> 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 language="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 <methodname>delete()</methodname>
            Methode des Kalender Services, und des Angebens der Bearbeitungs <acronym>URL</acronym>
            des Events durchgeführt werden, oder durch Aufruf der eigenen
            <methodname>delete()</methodname> Methode des Events.
        </para>

        <para>
            In jedem Fall, wird das gelöschte Event trotzdem noch am Privaten Event Feed des
            Benutzers aufscheinen wenn ein <property>updateMin</property> Abfrage Parameter
            angegeben wurde. Gelöschte Events können von normalen Events unterschieden werden weil
            Sie Ihre eigene <property>eventStatus</property> Eigenschaft auf
            "http://schemas.google.com/g/2005#event.canceled" gesetzt haben.
        </para>

        <programlisting language="php"><![CDATA[
// Option 1: Events können direkt gelöscht werden
$event->delete();
]]></programlisting>
        <programlisting language="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 <acronym>URL</acronym>
            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 <property>author</property> Eigenschaft und der Kommentar Text in der
            <property>content</property> Eigenschaft gespeichert.
        </para>

        <programlisting language="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>