LiveDocx ist ein SOAP-Service, der es Entwicklern erlaubt, MS Word Dokumente zu erstellen, indem strukturierte Daten von PHP mit einem Template kombiniert werden, die in einer MS Word-kompatiblen Anwendung erstellt wurden. Das resultierende Dokument kann als PDF, DOCX, DOC, HTML oder RTF Datei gespeichert werden. LiveDocx implementiert Mail-Merge in PHP. Die Familie der Zend_Service_LiveDocx Komponenten bietet ein klares und einfaches Interface zur LiveDocx API und bietet zusätzlich Funktionalitäten, um die Geschwindigkeit im Netzwerk zu erhöhen. Wenn man zusätzlich zu diesem Kapitel des Handbuchs daran interessiert ist, mehr über Zend_Service_LiveDocx und den dahinterliegenden SOAP-Service LiveDocx zu lernen, kann man bei den folgenden Ressourcen nachsehen: Mitgelieferte Beispielanwendungen. Es gibt eine große Anzahl an Beispielanwendungen im Verzeichnis /demos/Zend/Service/LiveDocx der Zend Framework Distributionsdatei, oder der Trunk Version die vom standardmäßigen SVN Repository ausgecheckt werden kann. Diese sind dazu gedacht, schnell, in nur ein paar Minuten, mit Zend_Service_LiveDocx zurecht zu kommen. Zend_Service_LiveDocx Blog und Webseite. LiveDocx SOAP API Dokumentation. LiveDocx WSDL. LiveDocx Blog und Webseite. Bevor man damit beginnt LiveDocx zu verwenden, muss man sich zuerst für einen Account anmelden. Der Account ist komplett kostenlos, und es muss nur ein Benutzername, ein Passwort und eine E-Mail-Adresse eingegeben werden. Die Anmeldedaten werden mit der E-Mail-Adresse verknüpft, die man angibt, deshalb sollte man vorsichtig tippen. LiveDocx unterscheidet zwischen den folgenden Ausdrücken: 1) Template und 2) Dokument. Um die Dokumentation und auch die aktuelle API vollständig zu verstehen, ist es wichtig dass jeder Programmierer der LiveDocx ausliefert, den Unterschied versteht. Der Ausdruck Template wird verwendet, um auf eine Eingabedatei zu verweisen, die in einer Textverarbeitung erstellt wurde und Formatierungen sowie Textfelder enthält. Man kann ein Beispieltemplate herunterladen, welches als DOCX Datei gespeichert ist. Der Ausdruck Dokument wird verwendet, um auf eine Ausgabedatei zu verweisen, welche die Templatedatei enthält, zusammen mit Daten - z.B. das fertiggestellte Dokument. Man kann ein Beispieldokument herunterlaen, welches als PDF Datei gespeichert ist. LiveDocx unterstützt die folgenden Dateiformate: Templates können in jedem der folgenden Dateiformate gespeichert werden: DOCX - Office Open XML Format DOC - Microsoft Word DOC Format RTF - Rich-Text-Dateiformat TXD - TX Text Control Format Das resultierende Dokument kann in jedem der folgenden Dateiformate gespeichert werden: DOCX - Office Open XML Format DOC - Microsoft Word DOC Format HTML - XHTML 1.0 Transitional Format RTF - Rich-Text-Dateiformat PDF - Acrobat Portable Document Format TXD - TX Text Control Format TXT - ANSI reiner Text Das resultierende Dokument kann in jedem der folgenden grafischen Dateiformate gespeichert werden: BMP - Bitmap Bildformat GIF - Graphics Interchange Format JPG - Joint Photographic Experts Group Format PNG - Portable Network Graphics Format TIFF - Tagged Image File Format WMF - Windows Meta File Format Zend_Service_LiveDocx_MailMerge ist das Mail-Merge-Objekt in der Zend_Service_LiveDocx Familie. Der Prozess der Erstellung des Dokuments kann mit der folgenden Gleichung vereinfacht dargestellt werden: Template + Daten = Dokument Oder durch das folgende Diagramm ausgedrückt werden: Daten werden in ein Template eingefügt, um ein Dokument zu erstellen. Ein Template, das in einer Textverarbeitungsanwendung, wie Microsoft Word, erstellt wird, wird in LiveDocx geladen. Daten werden in das Template eingesetzt und das resultierende Dokument wird in jedes der unterstützten Formate gespeichert. Man muss damit beginnen Microsoft Word zu starten und ein neues Dokument zu erstellen. Als nächstes wird der Dialog Felder geöffnet. Er sieht wie folgt aus: Dialogbox Felder in Microsoft Word 2007. Durch Verwendung dieses Dialogs kann man die benötigten Merge-Felder in das eigene Dokument einfügen. Anbei ist ein Screenshot der Lizenzvereinbarung in Microsoft Word 2007. Die Merge-Felder sind als { MERGEFIELD FieldName } markiert: Das Template in Microsoft Word 2007. Jetzt muss das Template als template.docx gespeichert werden. Im nächsten Schritt vereinen wir die Merge-Felder mit textuellen Daten von PHP. Unterteiltes Template in Microsoft Word 2007. Um die Merge Felder, im vorher unterteilten Screenshot des Templates, in Microsoft Word auszufüllen, muss das folgende geschrieben werden: setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setLocalTemplate('template.docx'); $phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9') ->assign('licensee', 'Henry Döner-Meyer') ->assign('company', 'Co-Operation'); $phpLiveDocx->createDocument(); $document = $phpLiveDocx->retrieveDocument('pdf'); file_put_contents('document.pdf', $document); ]]> Das resultierende Dokument wird auf der Festplatte in die Datei document.pdf geschrieben. Diese Datei kann nun weiter bearbeitet, per E-Eail versendet oder einfach angezeigt werden, wie anbei im Document Viewer 2.26.1 auf Ubuntu 9.04 gezeigt: Resultierendes Dokument als PDF im Document Viewer 2.26.1. Zend_Service_LiveDocx_MailMerge erlaubt es Entwicklern eine beliebige Anzahl an Text-Feldern in ein Template einzufügen. Diese Text-Felder werden mit Daten gefüllt, wenn createDocument() aufgerufen wird. Zusätzlich zu Textfeldern ist es auch möglich, spezielle Regionen eines Dokuments anzugeben, die wiederholt werden sollen. In einer Telefonrechnung ist es z.b. notwendig, eine Liste aller Verbindungen, inklusive der Zielnummern, der Dauer und den Kosten jedes Anrufs abzubilden,. Diese Funktion der wiederholten Zeile kann mit sogenannten Blöcken erzielt werden. Blöcke sind einfach Regionen eines Dokuments, welche wiederholt werden wenn createDocument() aufgerufen wird. In einem Block kann eine beliebige Anzahl an Block-Feldern spezifiziert werden. Blöcke bestehen aus zwei zusammenhängenden Sprungmarken mit eindeutigen Namen. Der folgende Screenshot zeigt diese Sprungmarken und deren Namen in Rot: Das Format eines Blocks ist wie folgt: Zum Beispiel: Der Inhalt eines Blocks wird wiederholt, bis alle zugeordneten Daten in Blockfeldern des Templates eingefügt wurden. Die Daten der Blockfelder werden in PHP als mehrfach-assoziatives Array spezifiziert. Der folgende Screenshot eines Templates in Microsoft Word 2007 zeigt wie Blockfelder verwendet werden: Template, welches Blöcke in Microsoft Word 2007 zeigt. Der folgende Code füllt das obige Template mit Daten. setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setLocalTemplate('template.doc'); $billConnections = array( array( 'connection_number' => '+49 421 335 912', 'connection_duration' => '00:00:07', 'fee' => '€ 0.03', ), array( 'connection_number' => '+49 421 335 913', 'connection_duration' => '00:00:07', 'fee' => '€ 0.03', ), array( 'connection_number' => '+49 421 335 914', 'connection_duration' => '00:00:07', 'fee' => '€ 0.03', ), array( 'connection_number' => '+49 421 335 916', 'connection_duration' => '00:00:07', 'fee' => '€ 0.03', ), ); $phpLiveDocx->assign('connection', $billConnections); // ... andere Daten hier zuweisen ... $phpLiveDocx->createDocument(); $document = $phpLiveDocx->retrieveDocument('pdf'); file_put_contents('document.pdf', $document); ]]> Die Daten, welche im Array $billConnections spezifiziert sind, werden im Template im Block 'connection' wiederholt. Die Schlüssel des Arrays (connection_number, connection_duration und fee) sind die Namen der Blockfelder - deren Daten werden bei jeder Iteration in einer Zeile eingefügt. Das resultierende Dokument wird auf der Festplatte in die Datei document.pdf geschrieben. Diese Datei kann anschließend nachbearbietet, per E-Mail gesendet, oder einfach dargestellt werden, wie anbei im Document Viewer 2.26.1 unter Ubuntu 9.04 gezeigt: Das resultierende Dokument als PDF im Document Viewer 2.26.1. Man kann die DOC Template Datei und das resultierende PDF Dokument hier herunterladen. BEACHTE: Blöcke können nicht verschachtelt werden. Zusätzlich zu den Dateiformaten für Dokumente erlaubt es Zend_Service_LiveDocx_MailMerge auch Dokumente als eine Anzahl von Bildern zu speichern (BMP, GIF, JPG, PNG und TIFF). Jede Seite des Dokuments wird als eine Datei gespeichert. Das folgende Beispiel zeigt die Verwendung von getBitmaps($fromPage, $toPage, $zoomFactor, $format) und getAllBitmaps($zoomFactor, $format). $fromPage ist die untere Grenze der Seitenzahl des Bereichs an Seiten, die als Bilder zurückgegeben werden sollen und $toPage ist die obere Grenze der Seitenzahlen. $zoomFactor ist die Größe der Bilder als Prozentwert relativ zur originalen Seitengröße. Der Bereich dieses Parameters ist von 10 bis 400. $format ist das Format des Bildes, welches von dieser Methode zurückgegeben wird. Die unterstützten Formate erhält man, wenn man getImageFormats() aufruft. setLocale('en_US'); $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge(); $phpLiveDocx->setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setLocalTemplate('template.docx'); $phpLiveDocx->assign('software', 'Magic Graphical Compression Suite v1.9') ->assign('licensee', 'Daï Lemaitre') ->assign('company', 'Megasoft Co-operation') ->assign('date', $date->get(Zend_Date::DATE_LONG)) ->assign('time', $date->get(Zend_Date::TIME_LONG)) ->assign('city', 'Lyon') ->assign('country', 'France'); $phpLiveDocx->createDocument(); // Alle Bitmaps holen // (zoomFactor, format) $bitmaps = $phpLiveDocx->getAllBitmaps(100, 'png'); // Nur Bitmaps im spezifizierten Bereich erhalten // (fromPage, toPage, zoomFactor, format) // $bitmaps = $phpLiveDocx->getBitmaps(2, 2, 100, 'png'); foreach ($bitmaps as $pageNumber => $bitmapData) { $filename = sprintf('documentPage%d.png', $pageNumber); file_put_contents($filename, $bitmapData); } ]]> Das produziert zwei Bilder (documentPage1.png und documentPage2.png) und schreibt diese auf die Festplatte in das gleiche Verzeichnis wie die ausführbare PHP-Datei. documentPage1.png. documentPage2.png. Templates können lokal auf der Client-Maschine gespeichert werden oder remote auf dem Server. Jede Variante hat Vorteile und Nachteile. Im Falle, dass ein Template lokal gespeichert ist, muss es bei jeder Anfrage vom Client auf den Server transferiert werden. Wenn sich der Inhalt vom Templates selten ändert, ist dieser Weg sehr ineffizient. Ähnlich auch, wenn das Template eine Größe von mehreren Megabyte hat, kann es eine beträchtliche Zeit dauern, es auf den Server zu transferieren. Lokale Templates sind in Situationen sinnvoll, in denen der Inhalt des Templates konstant geändert wird. Der folgende Code zeigt, wie man ein lokales Template verwendet. setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setLocalTemplate('./template.docx'); // Daten hinzufügen und das Dokument erstellen ]]> Im Falle, dass ein Template remote gespeichert ist, wird es nur einmal auf den Server geladen und anschließend bei allen nachfolgenden Anfragen darauf referenziert. Natürlich ist es viel schneller, als ein lokales Template zu verwenden, da das Template nicht bei jeder Anfrage übertragen werden muss. Für Anwendungen bei denen die Geschwindigkeit kritisch ist, wird es empfohlen die Remote-Template-Methode zu verwenden. Der folgende Code zeigt, wie ein Template auf den Server übertragen wird: setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->uploadTemplate('template.docx'); ]]> Der folgende Code zeigt, wie auf das remote gespeicherte Template bei allen weiteren Anfragen referenziert wird: setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setRemoteTemplate('template.docx'); // assign data and create document ]]> Zend_Service_LiveDocx_MailMerge bietet eine Anzahl an Methoden um Informationen über Feldnamen, vorhandene Schriftarten und unterstützte Formate zu erhalten. Der folgende Code gibt ein Array aller Feldnamen im angegebenen Template zurück und zeigt diese an. Diese Funktionalität ist nützlich, wenn man eine Anwendung erstellt, in welcher der Endbenutzer das Template aktualisieren kann. setUsername('myUsername') ->setPassword('myPassword'); $templateName = 'template-1-text-field.docx'; $phpLiveDocx->setLocalTemplate($templateName); $fieldNames = $phpLiveDocx->getFieldNames(); foreach ($fieldNames as $fieldName) { printf('- %s%s', $fieldName, PHP_EOL); } ]]> Der folgende Code zeigt ein Array aller Blockfeldnamen im angegebenen Template an. Diese Funktionalität ist nützlich, wenn man eine Anwendung erstellt, in welcher der Endbenutzer das Template aktualisieren kann. Bevor solche Templates veröffentlicht werden können, ist es notwendig, die Namen der enthaltenen Blockfelder herauszufinden. setUsername('myUsername') ->setPassword('myPassword'); $templateName = 'template-block-fields.doc'; $phpLiveDocx->setLocalTemplate($templateName); $blockNames = $phpLiveDocx->getBlockNames(); foreach ($blockNames as $blockName) { $blockFieldNames = $phpLiveDocx->getBlockFieldNames($blockName); foreach ($blockFieldNames as $blockFieldName) { printf('- %s::%s%s', $blockName, $blockFieldName, PHP_EOL); } } ]]> Der folgende Code zeigt ein Array aller auf dem Server installierten Schriftarten an. Diese Methode kann verwendet werden, um eine Liste von Schriftarten anzuzeigen, welche in einem Template verwendet werden können. Das ist nützlich, um den Endbenutzer über die auf dem Server installierten Schriften zu informieren, da nur diese Schriftarten in einem Template verwendet werden können. Im Falle, dass ein Template Schriften enthält, welche auf dem Server nicht enthalten sind, wird eine andere Schriftart verwendet. Dies kann zu unerwünschten Ergebnissen führen. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getFontNames()); ]]> BEACHTE: Da sich der Rückgabewert diese Methode sehr selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B. Zend_Cache - das macht die Anwendung sichtbar schneller. Der folgende Code zeigt ein Array aller unterstützten Dateiformate für Templates. Diese Methode ist partiell nützlich im Fall, dass eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt, das Eingabeformat für den Erstellungsprozess des Dokuments auszuwählen. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getTemplateFormats()); ]]> BEACHTE: Da sich der Rückgabewert diese Methode sehr selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B. Zend_Cache - das macht die Anwendung sichtbar schneller. Der folgende Code zeigt ein Array aller unterstützten Dateiformate für Dokumente. Diese Methode ist besonders nützlich, falls eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt, das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getDocumentFormats()); ]]> Der folgende Code zeigt ein Array aller unterstützten Dateiformate für Bilder. Diese Methode ist besonders nützlich, falls eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt, das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getImageFormats()); ]]> BEACHTE: Da sich der Rückgabewert diese Methode sehr selten ändert, ist es sehr empfehlenswert einen Cache zu verwenden, wie z.B. Zend_Cache - das macht die Anwendung sichtbar schneller.