LiveDocx ist ein SOAP Service der es Entwicklern erlaubt Word Dokumente zu erstellen indem strukturierte Daten von PHP mit einem Template kombiniert werden, die in einer Word Bearbeitung 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 das dahinterliegende 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 Distributiondatei, 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 mann muss nur einen Benutzernamen, ein Passwort und eine E-Mail Adresse spezifizieren. Die Anmeldedaten werden mit der Email Adresse verknüpft, welche 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 das jeder Programmierer der LiveDocx ausliefert, den Unterschied versteht. Der Ausdruck Template wird verwendet um auf eine Eingabedatei zu verweisen, die in einem Word Prozessor erstellt wurde, und Formatierungen sowie Textfelder enthält. Man kann ein Beispieltemplate downloaden, 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 downloaden, 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 File Format 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 Image Format 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 (größer darstellen). Ein Template das in einer Word Bearbeitungsanwendung, wie Microsoft Word, erstellt wird, wurd in LiveDocx geladen. Daten werden kann 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 (größer darstellen). Durch Verwendung dieses Dialogs kann man die benötigten Merge-Felder in das eigene Dokument einfügen. Anbei ist ein Screenshot der Lizenz Vereinbarung in Microsoft Word 2007. Die Merge Felder sind als { MERGEFIELD FieldName } markiert: Das Template in Microsoft Word 2007 (größer darstellen). Jetzt muss das Template als template.docx gespeichert werden. Im nächsten Schritt veröffentlichen wir die Merge-Felder mit textuellen Daten von PHP. Unterteiltes Template in Microsoft Word 2007 (größer darstellen). 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 die Festplatte in die Datei document.pdf geschrieben. Diese Datei kann nun weiter bearbeitet, per Email 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 (größer darstellen). Zend_Service_LiveDocx_MailMerge erlaubt es Entwicklern eine beliebige Anzahl an Text Feldern in ein Template einzufügen. Diese textfelder werden mit Daten gefüllt wenn createDocument() aufgerufen wird. Zusätzlich zu Textfeldern ist es auch mäglich spezielle Regionen eines Dokuments zu spezifizieren, welche 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 auszudrucken. 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 Dokument-Zielen mit einem eindeutigen Namen. Der folgende Screenshot zeigt diese Ziele und deren Namen in Rot: (größer darstellen). 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 (größer darstellen). 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 anhängen ... $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 die Festplatte in die Datei document.pdf geschrieben. Diese Datei kann anschließend nachbearbietet, per Email 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 (größer darstellen). 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 Bild zurückgegeben werden soll, 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 der Festplatte in das gleiche Verzeichnis wie die ausführbare PHP Datei. documentPage1.png (größer darstellen). documentPage2.png (größer darstellen). Templates können lokal, auf der Client Maschine, gespeichert werden, oder remote auf dem Server. Jede Variante hat Vorteile und Nachteile. Im Falle das ein Templage 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 Fall das 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 das 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 retourniert und zeigt ein Array aller Feldnamen im spezifizierten Template an. Diese Funktionalität ist nützlich, wenn man eine Anwendung erstellt, in welcher der End-Benutzer 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 retourniert und zeigt ein Array aller Block Feldnamen im spezifizierten Template an. Diese Funktionalität ist nützlich, wenn man eine Anwendung erstellt, in welcher der End-Benutzer 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 retourniert und 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 das ein Template Schriften enthänt, 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 retourniert und zeigt ein Array aller unterstützten Dateiformate für Templates. Diese Methode ist partiell nützlich im Fall das eine Kombinationsbox 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 retourniert und zeigt ein Array aller unterstützten Dateiformate für Dokumente. Diese Methode ist partiell nützlich im Fall das eine Kombinationsliste 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 retourniert und zeigt ein Array aller unterstützten Dateiformate für Bilder. Diese Methode ist partiell nützlich im Fall das eine Kombinationsliste 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.