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:

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:

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

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:

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

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

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

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

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

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

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge()

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

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

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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