Google Kalender verwendenDie Zend_Gdata_Calendar Klasse kann verwendet werden, um Events im Online Google Kalender Service zu sehen, erstellen, updaten und löschen. Siehe » http://code.google.com/apis/calendar/overview.html für weitere Informationen über die Google Kalender API. Zum Kalender Service verbindenDie 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. 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 Zend_Gdata_Calendar Instanz an diesen Client. AuthentifizierungDie Google Kalender API 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:
Die Zend_Gdata 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 Authentifizierungs Sektion dieses Handbuches, oder in die » Authentifizierungs Übersicht im Google Data API Entwickler Guide gesehen werden. Eine Service Instanz erstellenUm mit dem Google Kalender zu interagieren, bietet diese Bibliothek die Zend_Gdata_Calendar 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. Sobald ein Authentifizierung Schema ausgewählt wurde, besteht der nächste Schritt darin eine Instanz von Zend_Gdata_Calendar zu erstellen. Der Klassen Konstruktor nimmt eine Instanz von Zend_Http_Client 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 Zend_Http_Client erstellt. Das folgende Beispiel zeigt wie man eine Kalender Service Klasse erstellt und dabei die ClientAuth Authentifizierung verwendet:
Ein Kalender Service der AuthSub verwendet, kann ähnlich erstellt werden, durch eine etwas längere Schreibweise:
Schlußendlich, kann ein nicht authentifizierter Server erstellt werden um Ihn entweder mit öffentlichen Feeds oder MagicCookie Authentifizierung zu verwenden:
Es ist zu beachten das die MagicCookie Authentifizierung nicht mit der HTTP 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. Eine Kalender Liste empfangenDer 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 "hidden" markiert sind, auch vorhanden sind. 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.
Der Aufruf von getCalendarListFeed() erstellt eine neue Instanz von Zend_Gdata_Calendar_ListFeed die jeden vorhandenen Kalender als Instanz von Zend_Gdata_Calendar_ListEntry 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.
Events erhaltenWie die Liste der Kalender können auch die Events empfangen werden durch Verwendung der Zend_Gdata_Calendar Service Klasse. Die zurückgegebene Event Liste ist vom Typ Zend_Gdata_Calendar_EventFeed und enthält jedes Event als Instanz von Zend_Gdata_Calendar_EventEntry. Wie vorher, erlauben die in der Instanz des Event Feeds enthaltenen Accessoren und der Iterator das individuelle Events inspiziert werden können. AbfragenWenn Events mit der Kalender API empfangen werden, werden speziell erstellte Abfrage URLs verwendet um zu beschreiben welche Events zurückgegeben werden sollten. Die Zend_Gdata_Calendar_EventQuery Klasse vereinfacht diese Aufgabe durch automatische Erstellung einer Abfrage URL basierend auf den gegebenen Parametern. Eine komplette Liste dieser Parameter ist in der » Abfrage Sektion des Google Data API Protokoll Referenz enthalten. Trotzdem gibt es drei Parameter die es Wert sind speziell genannt zu werden:
Events in der Reihenfolge Ihres Startzeitpunktes erhaltenDas folgende Beispiel zeigt die Verwendung der Zend_Gdata_Query 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 "private-magicCookieValue" 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.
Zusätzliche Eigenschaften wie ID, Autor, Wann, Event Status, Sichtbarkeit, Web Inhalt, und Inhalt, sowie andere sind innerhalb von Zend_Gdata_Calendar_EventEntry vorhanden. Siehe die » Zend Framework API Dokumentation und die » Lalender Protokol Referenz für eine komplette Liste. Events in einem speziellen Datumsbereich empfangenUm 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 "$query->setFutureevents('true')" entfernt werden muß, da futureevents die Werte von startMin und startMax überschreibt.
Es ist zu beachten das startMin inklusive ist, wobei startMax exklusive ist. Als Ergebnis, werden nur die Events bis 2006-12-15 23:59:59 zurückgegeben. Events durch eine Volltext Abfrage erhaltenUm alle Events auszugeben welche ein spezielles Wort, zum Beispiel "Hundefutter" enthalten, muß die setQuery() Methode verwendet werden wenn die Abfrage erstellt wird.
Individuelle Events erhaltenIndividuelle Events können empfangen werden indem deren Event ID als Teil der Abfrage spezifiziert wird. Statt getCalendarEventFeed() auszurufen, sollte getCalendarEventEntry() aufgerufen werden.
In einer ähnlichen Weise kann Sie, wenn die Event URL bekannt ist, direkt an getCalendarEntry() ü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.
Events erstellenEin einmal vorkommendes Event erstellenEvents werden einem Kalender hinzugefügt indem eine Instanz von Zend_Gdata_EventEntry erstellt wird, und diese mit den richtigen Daten bekanntgegeben wird. Die Kalender Service Instanz (Zend_Gdata_Calendar) wird dann verwendet um das Event transparent in XML zu konvertieren und diese an den Kalender Server zu senden. Mindestens die folgenden Attribute sollten gesetzt werden:
Andere nützliche Attribute die optional gesetzt werden können sind unter anderem:
Für eine komplette Liste an Event Attributen, kann in die » Zend Framework API Documentation und die » Kalender Protokol Referenz 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 XML führen. Sobald das Event bekanntgegeben wurde, kann es zum Kalender Server hochgeladen werden durch seine Übergabe als Argument zur insertEvent() Funktion des Kalender Services.
Event Planungen und ErinnerungenDie Startzeit und Dauer eines Events werden durch die Werte seiner when Eigenschaften, startTime, endTime, und valueString ermittelt. StartTime und EndTime kontrollieren die Dauer des Events, während die valueString Eigenschaft aktuell nicht verwendet wird. Jeden Tag wiederkehrende Events können geplant werden indem nur das Datum spezifiziert und die Zeit ausgelassen wird wenn startTime und endTime gesetzt werden. Genauso können Events die keine Dauer haben spezifiziert werden indem endTime unterdrückt wird. In allen Fällen sollten Datums und Zeitwerte im » RFC3339 Format angegeben werden.
Das when 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. Damit ein reminder gültig ist, muß er zwei Attribute gesetzt haben: method und eine Zeit. Method akzeptiert einen der folgenden Strings: "alert", "email" oder "sms". Die Zeit sollte als Integer eingegeben werden und kann mit den Eigenschaften minutes, hours, days oder absoluteTime 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.
Wiederkehrende Events erstellenWiederkehrende 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 (» RFC 2445) beschrieben sind. Ausnahmen im Wiederholungs Pattern werden normalerweise durch ein ausgeprägtes recurrenceException 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. 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 » Kapitel über normale Elemente des Google Data API Entwickler Leitfadens gefunden werden, sowie in der RFC 2445.
QuickAdd verwendenQuickAdd 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 QuickAdd Eigenschaft erstellt, auf TRUE gesetzt und der frei definierbare Text als content Eigenschaft gespeichert werden.
Events bearbeitenSobald 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 save() Methode des Events die Änderungen an den Kalender Server und gibt eine Kopie des Events zurück wie es auf dem Server erstellt wurde. Im Fall das ein anderer Benutzer das Event modifiziert hat seitdem die lokale Kopie empfangen wurde, wird die save() 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.
Events löschenKalender Events können entweder durch den Aufruf der delete() Methode des Kalender Services, und des Angebens der Bearbeitungs URL des Events durchgeführt werden, oder durch Aufruf der eigenen delete() Methode des Events. In jedem Fall, wird das gelöschte Event trotzdem noch am Privaten Event Feed des Benutzers aufscheinen wenn ein updateMin Abfrage Parameter angegeben wurde. Gelöschte Events können von normalen Events unterschieden werden weil Sie Ihre eigene eventStatus Eigenschaft auf "http://schemas.google.com/g/2005#event.canceled" gesetzt haben.
Auf Event Kommentare zugreifenDen 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ß. 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 author Eigenschaft und der Kommentar Text in der content Eigenschaft gespeichert.
|
|