Antes de poder empezar a usar LiveDocx, primero debe registrarse para obtener una cuenta. La cuenta es completamente gratuita y solo necesita especificar un nombre de usuario, una contraseña y una dirección de correo electrónico. Sus credenciales de acceso se enviarán a la dirección de correo electrónico que proporcione, así que escríbala con cuidado.

LiveDocx diferencia entre los siguientes términos: 1) plantilla y 2) documento. Para comprender plenamente la documentación y, de hecho, la propia API, es importante que cualquier programador que utilice LiveDocx entienda la diferencia.

El término plantilla se utiliza para referirse al archivo de entrada, creado en un procesador de texto, que contiene el formato y los campos de texto. Puede descargar una plantilla de ejemplo, almacenada como archivo DOCX. El término documento se utiliza para referirse al archivo de salida que contiene la plantilla, rellenada con datos; es decir, el documento terminado. Puede descargar un documento de ejemplo, almacenado como archivo PDF.

LiveDocx admite los siguientes formatos de archivo:

El proceso de generación de documentos puede simplificarse con la siguiente ecuación:

Plantilla + Datos = Documento

O expresado mediante el siguiente diagrama:

Los datos se insertan en la plantilla para crear un documento.

Una plantilla, creada en una aplicación de procesamiento de texto, como Microsoft Word, se carga en LiveDocx. Luego, los datos se insertan en la plantilla y el documento resultante se guarda en cualquier formato compatible.

Comience abriendo Microsoft Word y creando un nuevo documento. A continuación, abra el cuadro de diálogo Campo. Este tiene el siguiente aspecto:

Cuadro de diálogo Campo de Microsoft Word 2007.

Usando este diálogo, puede insertar los campos de combinación requeridos en su documento. A continuación se muestra una captura de pantalla de un acuerdo de licencia en Microsoft Word 2007. Los campos de combinación se marcan como { MERGEFIELD FieldName }:

Plantilla en Microsoft Word 2007.

Ahora, guarde la plantilla como template.docx.

En el siguiente paso, vamos a rellenar los campos de combinación con datos textuales desde PHP.

Plantilla recortada en Microsoft Word 2007.

Para rellenar los campos de combinación en la captura de pantalla recortada anterior de la plantilla en Microsoft Word, todo lo que tenemos que codificar es lo siguiente:

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

El documento resultante se escribe en disco en el archivo document.pdf. Este archivo ahora puede postprocesarse, enviarse por correo electrónico o simplemente mostrarse, como se ilustra a continuación en Document Viewer 2.26.1 en Ubuntu 9.04:

Documento resultante como PDF en Document Viewer 2.26.1.

Usando Zend_Service_LiveDocx_MailMerge también es posible combinar imágenes en una plantilla. Esta funcionalidad es útil, por ejemplo, en el caso de una aplicación de identificación para una conferencia. Además del nombre y el nombre de la empresa que deben aparecer en la identificación, es posible insertar una foto del delegado, usando la API.

Aunque suena un poco contraintuitivo, la combinación de imágenes también funciona con campos de texto, como se describe en la sección anterior. De hecho, insertar un campo de texto para una imagen es idéntico a insertar un campo de texto para información textual. La única diferencia es la convención de nomenclatura del campo de texto. Mientras que un campo de texto para información textual puede tener (casi) cualquier identificador, un campo de texto para una imagen debe comenzar con image:. Por ejemplo, en el caso de nuestra aplicación de identificación, tendríamos los siguientes 3 campos:

El campo de texto, en el que se insertarán los datos de imagen se llama image:photo y puede rellenarse igual que cualquier otro campo de texto, usando el método assign. Los campos de texto name y company son campos de texto regulares para información textual.

Antes de insertar datos gráficos, primero debemos subir la imagen al servidor backend de LiveDocx. Esto puede lograrse usando el método uploadImage($filename).

El siguiente fragmento de código ilustra el flujo:

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

$phpLiveDocx->setUsername('username')
            ->setPassword('password');

$photoFilename = 'dailemaitre.jpg';

if (!$phpLiveDocx->imageExists($photoFilename)) {
    $phpLiveDocx->uploadImage($photoFilename);
}

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

$phpLiveDocx->assign('name',        'Daï Lemaitre')
            ->assign('company',     'Megasoft Co-operation')
            ->assign('date',        Zend_Date::now()->toString(Zend_Date::DATE_LONG))
            ->assign('image:photo', $photoFilename);

$phpLiveDocx->createDocument();

$document = $phpLiveDocx->retrieveDocument('pdf');

file_put_contents('document.pdf', $document);

$phpLiveDocx->deleteImage($photoFilename);

Tenga en cuenta que todas las imágenes subidas a su cuenta de LiveDocx deben tener un nombre de archivo único. En el caso de que solo pretenda usar la imagen una vez (como es probable para nuestra aplicación de identificación), tiene sentido eliminarla inmediatamente del backend, usando el método deleteImage($filename).

Zend_Service_LiveDocx_MailMerge permite a los diseñadores insertar cualquier número de campos de texto en una plantilla. Estos campos de texto se rellenan con datos cuando se llama a createDocument().

Además de los campos de texto, también es posible especificar regiones de un documento, que deben repetirse.

Por ejemplo, en una factura telefónica es necesario imprimir una lista de todas las conexiones, incluyendo el número de destino, la duración y el coste de cada llamada. Esta funcionalidad de fila repetida puede lograrse con los llamados bloques.

Los bloques son simplemente regiones de un documento, que se repiten cuando se llama a createDocument(). En un bloque se puede especificar cualquier número de campos de bloque.

Los bloques constan de dos objetivos de documento consecutivos con un nombre único. La siguiente captura de pantalla ilustra estos objetivos y sus nombres en rojo:

El formato de un bloque es el siguiente:

blockStart_ + unique name
blockEnd_ + unique name

Por ejemplo:

blockStart_block1
blockEnd_block1

El contenido de un bloque se repite, hasta que se hayan inyectado en la plantilla todos los datos asignados en los campos de bloque. Los datos para los campos de bloque se especifican en PHP como un array multi-asociativo.

La siguiente captura de pantalla de una plantilla en Microsoft Word 2007 muestra cómo se usan los campos de bloque:

Plantilla, ilustrando bloques en Microsoft Word 2007.

El siguiente código rellena la plantilla anterior con datos.

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

// ... assign other data here ...

$phpLiveDocx->createDocument();
$document = $phpLiveDocx->retrieveDocument('pdf');
file_put_contents('document.pdf', $document);

Los datos, especificados en el array $billConnections, se repiten en la plantilla en el bloque connection. Las claves del array (connection_number, connection_duration y fee) son los nombres de los campos de bloque; sus datos se insertan, una fila por iteración.

El documento resultante se escribe en disco en el archivo document.pdf. Este archivo ahora puede postprocesarse, enviarse por correo electrónico o simplemente mostrarse, como se ilustra a continuación en Document Viewer 2.26.1 en Ubuntu 9.04:

Documento resultante como PDF en Document Viewer 2.26.1.

Puede descargar el archivo de DOC plantilla y el documento PDF resultante.

NOTA: los bloques no se pueden anidar.

Además de los formatos de archivo de documento, Zend_Service_LiveDocx_MailMerge también permite exportar documentos a varios formatos de archivo de imagen (BMP, GIF, JPG, PNG y TIFF). Cada página del documento se guarda en un archivo.

El siguiente ejemplo ilustra el uso de getBitmaps($fromPage, $toPage, $zoomFactor, $format) y getAllBitmaps($zoomFactor, $format).

$fromPage es el número de página inferior del rango de páginas que debe devolverse como imagen y $toPage el número de página superior. $zoomFactor es el tamaño de las imágenes, como porcentaje, relativo al tamaño de página original. El rango de este parámetro es de 10 a 400. $format es el formato de las imágenes devueltas por este método. Los formatos compatibles pueden obtenerse llamando a getImageExportFormats().

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

// Get all bitmaps
// (zoomFactor, format)
$bitmaps = $phpLiveDocx->getAllBitmaps(100, 'png');

// Get just bitmaps in specified range
// (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);
}

Esto produce dos archivos (documentPage1.png y documentPage2.png) y los escribe en disco en el mismo directorio que el archivo PHP ejecutable.

documentPage1.png.

documentPage2.png.

Las plantillas pueden almacenarse localmente, en la máquina cliente, o remotamente, en el servidor. Cada enfoque tiene ventajas y desventajas.

En el caso de que una plantilla se almacene localmente, debe transferirse del cliente al servidor en cada solicitud. Si el contenido de la plantilla rara vez cambia, este enfoque es ineficiente. Del mismo modo, si la plantilla tiene varios megabytes de tamaño, puede tardar bastante tiempo en transferirse al servidor. Las plantillas locales son útiles en situaciones en las que el contenido de la plantilla cambia constantemente.

El siguiente código ilustra cómo usar una plantilla local.

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

$phpLiveDocx->setLocalTemplate('./template.docx');

// assign data and create document

En el caso de que una plantilla se almacene remotamente, se sube una vez al servidor y luego simplemente se referencia en todas las solicitudes posteriores. Obviamente, esto es mucho más rápido que usar una plantilla local, ya que la plantilla no tiene que transferirse en cada solicitud. Para aplicaciones críticas en velocidad, se recomienda usar el método de plantilla remota.

El siguiente código ilustra cómo subir una plantilla al servidor:

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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

El siguiente código ilustra cómo referenciar la plantilla almacenada remotamente en todas las solicitudes posteriores:

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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

// assign data and create document

Zend_Service_LiveDocx_MailMerge proporciona una serie de métodos para obtener información sobre nombres de campos, fuentes disponibles y formatos compatibles.

$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->getImageImportFormats());

$phpLiveDocx = new Zend_Service_LiveDocx_MailMerge();

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

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