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 can be stored locally, on the client machine, or remotely, on the server. There are advantages and disadvantages to each approach. In the case that a template is stored locally, it must be transfered from the client to the server on every request. If the content of the template rarely changes, this approach is inefficient. Similarly, if the template is several megabytes in size, it may take considerable time to transfer it to the server. Local template are useful in situations in which the content of the template is constantly changing. The following code illustrates how to use a local template. setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setLocalTemplate('./template.docx'); // assign data and create document ]]> In the case that a template is stored remotely, it is uploaded once to the server and then simply referenced on all subsequent requests. Obviously, this is much quicker than using a local template, as the template does not have to be transfered on every request. For speed critical applications, it is recommended to use the remote template method. The following code illustrates how to upload a template to the server: setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->uploadTemplate('template.docx'); ]]> The following code illustrates how to reference the remotely stored template on all subsequent requests: setUsername('myUsername') ->setPassword('myPassword'); $phpLiveDocx->setRemoteTemplate('template.docx'); // assign data and create document ]]> Zend_Service_LiveDocx_MailMerge provides a number of methods to get information on field names, available fonts and supported formats. The following code returns and displays an array of all field names in the specified template. This functionality is useful, in the case that you create an application, in which an end-user can update a template. 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); } ]]> The following code returns and displays an array of all block field names in the specified template. This functionality is useful, in the case that you create an application, in which an end-user can update a template. Before such templates can be populated, it is necessary to find out the names of the contained block fields. 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); } } ]]> The following code returns and displays an array of all fonts installed on the server. You can use this method to present a list of fonts which may be used in a template. It is important to inform the end-user about the fonts installed on the server, as only these fonts may be used in a template. In the case that a template contains fonts, which are not available on the server, font-substitution will take place. This may lead to undesirable results. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getFontNames()); ]]> NOTE: As the return value of this method changes very infrequently, it is highly recommended to use a cache, such as Zend_Cache - this will considerably speed up your application. The following code returns and displays an array of all supported template file formats. This method is particularly useful in the case that a combo list should be displayed that allows the end-user to select the input format of the documentation generation process. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getTemplateFormats()); ]]> NOTE: As the return value of this method changes very infrequently, it is highly recommended to use a cache, such as Zend_Cache - this will considerably speed up your application. The following code returns and displays an array of all supported document file formats. This method is particularly useful in the case that a combo list should be displayed that allows the end-user to select the output format of the documentation generation process. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getDocumentFormats()); ]]> The following code returns and displays an array of all supported image file formats. This method is particularly useful in the case that a combo list should be displayed that allows the end-user to select the output format of the documentation generation process. setUsername('myUsername') ->setPassword('myPassword'); Zend_Debug::dump($phpLiveDocx->getImageFormats()); ]]> NOTE: As the return value of this method changes very infrequently, it is highly recommended to use a cache, such as Zend_Cache - this will considerably speed up your application.