# Zend_Service_LiveDocx

## Einführung in LiveDocx

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.

### Für einen Account anmelden

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 einen Benutzernamen, 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.

### Templates und Dokumente

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.

### Unterstützte Dateiformate

LiveDocx unterstützt die folgenden Dateiformate:

#### Template Dateiformate (Eingabe)

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

#### Dokument Dateiformate (Ausgabe):

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

#### Bild Dateiformate (Ausgabe):

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

`Zend_Service_LiveDocx_MailMerge` ist das Mail-Merge-Objekt in der `Zend_Service_LiveDocx` Familie.

### Prozess der Dokumentenerstellung

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.

### Erstellen von Templates in Microsoft Word 2007

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:

    $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', '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.

### Gehobeneres Mail-Merge

`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 Text-Felder ist es auch möglich spezielle Regionen eines Dokuments zu spezifizieren, 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:

    blockStart_ + unique name
    blockEnd_ + unique name

Zum Beispiel:

    blockStart_block1
    blockEnd_block1

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.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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 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.

### Erstellen von Bitmap Bildern

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.

    $date = new Zend_Date();
    $date->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.

### Lokale vs. Remote Templates

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.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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:

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->setUsername('myUsername')
                ->setPassword('myPassword');

    $phpLiveDocx->uploadTemplate('template.docx');

Der folgende Code zeigt wie auf das remote gespeicherte Template bei allen weiteren Anfragen referenziert wird:

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->setUsername('myUsername')
                ->setPassword('myPassword');

    $phpLiveDocx->setRemoteTemplate('template.docx');

    // assign data and create document

### Informationen erhalten

`Zend_Service_LiveDocx_MailMerge` bietet eine Anzahl an Methoden um Informationen über Feldnamen, vorhandene Schriftarten und unterstützte Formate zu erhalten.

#### Ein Array an Feldnamen vom Template erhalten

Der folgende Code gibt ein Array aller Feldnamen im spezifizierten Template zurück und zeigt diese an. Diese Funktionalität ist nützlich, wenn man eine Anwendung erstellt, in welcher der End-Benutzer das Template aktualisieren kann.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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);
    }

#### Ein Array an Block Feldnamen vom Template erhalten

Der folgende Code 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.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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);
        }
    }

#### Ein Array von Schriftarten erhalten welche auf dem Server installiert sind

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.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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.

#### Ein Array an unterstützten Dateiformaten für Templates erhalten

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.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge()

    $phpLiveDocx->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.

#### Ein Array an unterstützten Dateiformaten für Dokumente erhalten

Der folgende Code zeigt ein Array aller unterstützten Dateiformate für Dokumente. Diese Methode ist partiell nützlich im Fall das eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt, das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->setUsername('myUsername')
                ->setPassword('myPassword');

    Zend_Debug::dump($phpLiveDocx->getDocumentFormats());

#### Ein Array an unterstützten Dateiformaten für Bilder erhalten

Der folgende Code zeigt ein Array aller unterstützten Dateiformate für Bilder. Diese Methode ist partiell nützlich im Fall das eine Auswahlliste angezeigt werden soll, welche es dem Endbenutzer erlaubt das Ausgabeformat für den Erstellungsprozess des Dokuments auszuwählen.

    $phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

    $phpLiveDocx->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.