2.4 Dokumentation 
Für jede Komponente der eZ Components ist Dokumentation in einer Menge und Qualität verfügbar, die besonders im PHP-Bereich ihres Gleichen sucht. Damit Sie auf Anhieb wissen, wo Sie bei auftretenden Problemen nachsehen können, werden die einzelnen Bestandteile der eZ Components-Dokumentation hier kurz vorgestellt.
2.4.1 API-Dokumentation 
Jede einzelne Datei, jede Klasse, jede Methode und jedes Attribut in eZ Components ist ausführlich im Quellcode dokumentiert. Zusätzlich finden Sie im Dokumentationsblock auf Klassenebene bei allen wichtigen Klassen ein Codebeispiel zu deren Verwendung. Durch die Nutzung des im PHP-Umfeld als Standard zu betrachtenden phpDocumentor-Formats [http://phpdoc.org ] , das eine PHP-spezifische Implementierung des bekannten JavaDoc ist, wird diese API-Dokumentation ebenfalls online im HTML-Format sowie zum Download bereitgestellt. In der HTML-Version finden Sie allerdings nur solche Bestandteile, die nicht als privat markiert sind, da nur diese für Sie nutzbar sind. Wollen Sie dennoch einen Blick in private Elemente werfen, können Sie die Dokumentation sehr übersichtlich im Code ansehen oder selbst mit Hilfe von phpDocumentor generieren.
Einige Elemente im Sourcecode von eZ Components sind explizit durch die Dokumentation als privat markiert, um die Nutzung außerhalb der Komponente zu verhindern. Dieses Vorgehen wurde aus zwei Gründen eingeführt:
| 1. | In PHP existiert keinerlei Mechanismus, um Freundschaftsbeziehungen zwischen Klassen zu definieren. So ist es nicht möglich, einer bestimmten Klasse den Zugriff auf private Mitglieder einer anderen Klasse explizit zu erlauben. Dieses Manko kann nur durch die genannte Technik simuliert werden. |
| 2. | Es kann vorkommen, dass ein bestimmter Teil einer Komponente zwar gut getestet und als stabil angesehen wird, die Diskussion über die API aber noch nicht abgeschlossen ist. Damit andere Bestandteile der Komponente trotzdem auf diese Teile zugreifen und die Funktionalitäten nutzen können, werden sie als privat markiert, um die offizielle API noch nicht endgültig festzulegen. |
Natürlich könnten Sie solche pseudo-privaten Deklarationen ignorieren, allerdings kann es dann schnell passieren, dass Ihre Applikation nach einem Update von eZ Components plötzlich den Dienst versagt. Schließlich gilt das Prinzip der Abwärtskompatibilität nur für die öffentliche API der eZ Components und private Bestandteile können jederzeit geändert werden. Aus diesem Grund raten wir davon ab, Elemente direkt anzusprechen, die in der Dokumentation als privat markiert wurden. Solche Elemente tauchen auch in der Onlinedokumentation nicht auf.
Neben der generierten Dokumentation finden Sie für jede Komponente eine Übersicht über deren Klassen, welche die Vererbungshierarchie widerspiegelt, ebenfalls online. In dieser Übersicht sind die wichtigsten Klassen explizit markiert, um den Einstieg in die Komponente zu erleichtern. Ein weiteres Feature der Onlinedokumentation ist die Verlinkung der API-Elemente untereinander. So werden die Klassen-, Methoden- und Attributnamen mit Links zur Dokumentation des entsprechenden Elements versehen.
Eine Übersicht über die API-Dokumentation für jede einzelne Version der Bibliothek finden Sie unter http://ez.no/doc/components/overview, die Dokumentation für die in diesem Buch vorgestellte Version 2007.1 ist unter der Adresse http://ez.no/doc/components/overview/2007.1 verfügbar. Daneben gibt es eine URL-Abkürzung, um auf die API-Übersicht der jeweils aktuellsten Version zuzugreifen (http://ez.no/doc/components/view/latest/), sowie die wöchentlich erzeugte Dokumentation des Entwicklungszweigs auf der Seite http://ez.no/doc/components/overview/trunk.
2.4.2 Anleitungen
Während die generierte API-Dokumentation ein hervorragendes Nachschlagewerk darstellt, ist sie doch recht nutzlos, wenn es darum geht, in die grundlegenden Benutzungskonzepte einer Komponente einzusteigen und sich einen Überblick über deren Fähigkeiten zu verschaffen. Aus diesem Grund enthält die Onlinedokumentation für jede Komponente eine ausführliche Anleitung (Tutorial), in der praktische Beispiele zur Verwendung der wichtigsten Klassen und Features vorgestellt und detailliert erklärt werden. Die bereits im vorherigen Abschnitt beschriebene Verlinkung der API-Elemente ist auch hier zu finden, womit Sie direkt aus einem Tutorial zu den für Sie interessanten Elementen gelangen können.
Die Onlinedokumentation komplexerer Komponenten wie der Template-Komponente enthält weitere Informationen. Für Template steht zum Beispiel die komplette Erweiterte-Bakkus-Naur-Form (EBNF) bereit, welche die Syntax der Template-Sprache beschreibt, sowie eine detaillierte Übersicht über alle Funktionen, Blöcke und Kontrollstrukturen der Template-Sprache. Näheres hierzu erfahren Sie auch in Kapitel 8, »Template«, das sich ausführlich mit der Template-Komponente befasst.
2.4.3 Mitgeliefertes
Die API-Dokumentation einer Komponente wird selbstverständlich immer mit der Komponente selbst geliefert, da sie sich direkt im Sourcecode befindet. Wenn Sie phpDocumentor installiert haben, können Sie so die HTML-Variante der Dokumentation aus Ihrer lokalen Kopie von eZ Components selbst generieren und hierbei sogar die Dokumentation von privaten Elementen erhalten.
Zusätzlich findet sich aber in jedem Komponenten-Verzeichnis (bei PEAR-Installation weicht dies ab) ein Verzeichnis namens docs, welches das Tutorial in reiner Textform sowie alle zugehörigen Beispiele als ausführbaren Sourcecode enthält. Zusätzlich finden Sie hier weiteren Beispielquellcode, den Sie als Ausgangspunkt Ihrer Entwicklung verwenden können.
Ebenfalls von großem Wert können die Unit-Tests einer Komponente sein, wenn es darum geht, einen ausführlichen Einblick in die Funktionsweise der einzelnen API-Elemente zu erhalten. In eZ Components werden sämtliche öffentlichen Methode getestet, sowohl mit validen als auch invaliden Werten. Letzteres, um das korrekte Werfen von Exceptions zu testen. Des Weiteren wird dem Code-Coverage-Wert der Unit-Tests ein hohes Maß an Bedeutung zugewiesen, um das Testen sämtlicher Funktionalitäten zu gewährleisten. Die Unit-Tests einer jeden Komponente finden Sie im Unterverzeichnis tests/.
2.4.4 Beispielapplikationen und Artikel
Außerdem existieren einige Artikel zum Thema eZ Components (http://ez.no/community/articles/development/ez_components) auf der eZ Systems-Website. Hier finden Sie unter anderem eine ausführliche Einführung in das Gesamtkonzept sowie umfangreiche Artikel zu den Komponenten PersistentObject, Template, Graph und anderen. In unregelmäßigen Abständen, meist jedoch zum Erscheinungstermin Gesamtpakets, erscheinen hier neue Artikel, die anhand einer kleinen Beispielapplikation die Funktionsweise einer Komponente erläutern und oft auch weitere Komponenten verwenden. Ebenfalls nützlich ist die Sammlung verschiedener Präsentationen zu eZ Components, die Sie unter http://ez.no/ezcomponents/presentations im PDF-Format herunterladen können.
Die Beispielapplikationen aus den genannten Artikeln sowie weitere Beispielanwendungen finden Sie auch im Subversion-Repository in den Unterverzeichnissen docs/examples/ und docs/articles/, wo ihnen auch der Text der Artikel im Klartext zur Verfügung steht. Wie Sie mit dem eZ Components-Entwicklungsrepository umgehen, erfahren Sie in Abschnitt 2.1.4, »SVN«.
2.4.5 Support
Wie Sie sehen, verfügen eZ Components über ein hohes Maß an Dokumentation, welches Ihnen in Kombination mit diesem Buch eine solide Basis für Ihre eigene Entwicklung liefert. Sollte dennoch mal eine Frage offen bleiben, stehen die eZ Components-Kernentwickler von eZ System ebenso wie eine stetig wachsende Entwickler- und Benutzer-Community auf der eZ Components-Mailingliste gerne für Fragen und Anregungen zur Verfügung. Sie erreichen die Mailingliste unter der Adresse components@lists.ez.no und können zur aktiven Teilnahme oder einfach zum Mitlesen der Liste unter der Adresse http://lists.ez.no/mailman/listinfo/components selbst beitreten. Hier werden neben dem Austausch von Erfahrungen auch Probleme und Ideen diskutiert, sodass Sie immer auf dem neusten Stand sind und sich selbst an der Entwicklung beteiligen können. Mehr zum Thema Beteiligung am Projekt erfahren Sie im folgenden Abschnitt 2.5, »Selbst etwas beisteuern«.
Eine weitere Anlaufstelle ist der Internet-Relay-Chat (IRC-Kanal) der eZ Components, in dem sich immer einige der Kernentwickler sowie Community-Kontributoren und eZ Components-Enthusiasten tummeln, die gerne bereit stehen, um Fragen zu beantworten und Ideen zu diskutieren. Den IRC-Kanal finden sie im Chat-Netzwerk Freenode [http://freenode.net/ ] unter dem Namen #ezcomponents.
Sollte der so geleistete Community-Support nicht ausreichen oder sollten Sie eine konstante Update- und Bugfix-Garantie benötigen, empfiehlt sich das kommerzielle Support-Angebot von eZ Systems unter http://ez.no/services. Eine weitere angebotene Serviceleistung sind professionelle Trainings und Seminare zum Thema eZ Components, die auch gerne in Ihren eigenen Räumen von einem qualifizierten Trainer abgehalten werden. Weitere Informationen hierzu finden Sie auf http://ez.no/services/training/ez_components_training. In vielen Fällen übernimmt sogar einer der Kernentwickler selbst das Training.
