Quick User Guide

Please, if you have questions about the installation, just contact us.

The goal of this section is to offer you a fast lane to get acquainted with the architecture and main functionalities of Docxpresso without the need of going over all the nitty-gritty details of the documentation.

Generalities

Docxpresso is a software library written in PHP (you need to have installed in your server PHP 5.3 or higher) that has been designed to generate data driven documents and reports in a web server (although it is also possible to run it from the command line interface (CLI)).

Docxpresso is much more than a library that helps you to transform HTML5 code into PDF documents. With the help of Docxpresso you can also generate in an equally simple fashion Word (.doc, .docx), Open Document (.odt) and Rich Text Format (.rtf) documents.

This is so because Docxpresso is based on the Open Document Format, so the generation of .odt and .doc is starightforward (MS Word directly interprets the generated documents without the need of any conversion or transformation) while the generation of .pdf, .docx or .rtf requires a further conversion that can be carried out by a copy of Libre Office or Open Office that you may download for free from the Internet.

Docxpresso offers you, besides the possibility of directly using HTML5 code to populate your document contents, a generous public API that allows for direct access to its core functionality, i.e. one may use its underlining methods to generate content with more versatility while all the format and styling is still coded in CSS style.

Docxpresso can be used as a standalone library or integrated within a framework or another software product (although some licensing restrictions may apply). Because of its open code policy, profuse documentation of its PHP code and ample functionality, Docxpresso is currently the more versatile PHP package for the generation of online documents.

Getting started

We will assume from now on that Docxpresso has been sucessfully installed (you may follow the detailed installation instructions for Linux & Unix-like systems or Windows) and that you are prepared to spend a few minutes getting acquainted with the library.

Let us start with the proptotypical Hello World! example but to go a little bit further we are going to generate a document with two paragraphs. The first paragraph will be generated out from HTML5 code while the second one (Good Bye World!) will use the core paragraph method

<?php
/**
 * This sample script inserts two simple paragraphs
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph as HTML
$doc->html(array('html' => '<p>Hello World!</p>'));
//insert a paragraph with the help of the paragraph method
$doc->paragraph(array('text' => 'Good Bye World!'));
//include in the render method the path where you want your document to be saved
$doc->render('hello_world' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'hello_world' . $format . '">Download document</a>';

DOWNLOAD:

Notice that because we have not set any styling option the diferent viewers may, for example, choose a different default font (MS Word uses Calibri while Libre and Open Office use Times New Roman).

So far so good but it is pretty clear that we are not going to get a job as designers with such a poor display.

Let us introduce some basic styling and some color to our document. Let us write the word world in bright red in both examples and also add some left indent to the paragraphs to better illustrate the procedure.

<?php
/**
 * This sample script inserts two simple paragraphs with some styling
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph as HTML
$doc->html(array('html' => '<p style="left-margin: 2cm" >Hello <span style="color: red">World</span>!</p>'));
//insert a paragraph with the help of the paragraph method
$doc->paragraph(array('style' => 'margin-left: 2cm'))
        ->text(array('text' => 'Good Bye '))
        ->text(array('text' => 'World ', 'style' => 'color: red'))
        ->text(array('text' => '!'));
//include in the render method the path where you want your document to be saved
$doc->render('hello_world_styles' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'hello_world_styles' . $format . '">Download document</a>';

DOWNLOAD:

A few comments are now due.

Regarding the HTML code: we have used inline styles for simplicity but we could have equally used standard CSS classes or ids to generate the first paragraph required formatting. We will ellaborate further on this point in the following.

Regarding the Docxpresso architecture: you probably have noticed that we have chained the paragraph and text methods something that may show pretty convenient to keep track of the document structure in a more visual way.

It is important to point out that Docxpresso is smart enough to preserve the natural document structure whenever needed, i.e. something like:

$doc->paragraph(array('style' => 'margin-left: 2cm'))
        ->text(array('text' => 'Good Bye '))
        ->text(array('text' => 'World ', 'style' => 'color: red'))
        ->text(array('text' => '!'))
    ->paragraph(array('style' => 'margin-left: 2cm'))
        ->text(array('text' => 'Another paragraph.'));

should render the same result that:

$doc->paragraph(array('style' => 'margin-left: 2cm'))
        ->text(array('text' => 'Good Bye '))
        ->text(array('text' => 'World ', 'style' => 'color: red'))
        ->text(array('text' => '!'))
$doc->paragraph(array('style' => 'margin-left: 2cm'))
        ->text(array('text' => 'Another paragraph.'));

because paragraphs can not be nested within a document.

In the cases where there is an ambiguity, i.e. the chained method can be nested or not, Docxpresso will nest unless instructed in the contrary by means of the end method (we will have the oportunity to see it at work further below).

Of course, chaining is just an option and not a must. We could have obtained the same result as above by means of the following code:

$p1 = $doc->paragraph(array('style' => 'margin-left: 2cm'))
$p1->text(array('text' => 'Good Bye '))
$p1->text(array('text' => 'World ', 'style' => 'color: red'))
$p1->text(array('text' => '!'))
$p2 = $doc->paragraph(array('style' => 'margin-left: 2cm'))
$p2->text(array('text' => 'Another paragraph.'));

Although in this case there is not such a big difference it is pretty simple to imagine that when we have to nest multiple elements, like it is often the case, the code can become pretty messy.

Indeed, given the choice, and jumping a little ahead, our preferred option would be:

$doc->paragraph()->style('margin-left: 2cm')
        ->text(array('text' => 'Good Bye '))
        ->text(array('text' => 'World ')->style('color: red'))
        ->text(array('text' => '!'))
$doc->paragraph()->style('margin-left: 2cm')
        ->text(array('text' => 'Another paragraph.'));

The above sample code is, in our opinion, the one that best reflects the structure of the underlining document while preserving a clear separation between content and formatting.

Although all of this is still pretty basic we hope that by now you may be getting the feeling that it may be worth the effort to continue and move to more sophisticated stuff!

An illustrative example

Rather than predating the contents of the documentation we would like to offer you here a reasonably extended, though simple, example that illustrates the capabilities of the package.

Our inmediate goal is to build a document with the following elements:

• a header,
• a few headings and paragraphs,
• an image,
• a footnote,
• a nicely formatted table and
• a nested list.

And to do so in two different ways:

• Exclusively through HTML5 + CSS code.
• By direct use of the Docxpresso public API.

Although, of course, both methods could, in general, be combined.

HTML5

<?php
/**
* This sample script generates a sample
* document out of HTML code
*/
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
$html='
<html>
<head>
<style>
* {font-family: Arial; font-size: 10pt}
h2 {margin: 25pt 0 5pt 0}
p {margin-bottom: 10pt}
th {background-color: #5B9BD5; padding: 3px 7px}
th p {color: #f6f6f6; font-weight: bold; font-size: 10pt; margin: 0}
td {padding: 3px 7px; border: 0.5pt solid #ffffff}
td p {color: #333; font-size: 10pt; margin: 0}
li {margin-bottom: 5pt}
li li {font-style: italic; color: #555;}
header {height: 1.5cm}
.headerTable {width: 15cm}
.headerTable td {border: none; border-bottom: 0.5pt solid #333}
.headerTable td.left {text-align: right; width: 5cm; background-color: #b74400}
.headerTable td.left p {color: #ffffff}
.headerTable td.middle {color: #333; width: 8cm}
.headerTable td.right {text-align: right; color: #333; width: 2cm}
.summary {margin: 10pt 40pt; text-align: justify}
.footnote {font-size: 9pt}
.image {text-align: center}
.nice {width: 12cm; margin: auto}
.firstCol {background-color: #5B9BD5;}
.firstCol p {color: #f6f6f6; font-weight: bold; font-size: 10pt; margin: 0}
.even {background-color: #BDD6EE;}
.odd {background-color: #DEEAF6}
</style>
</head>
<body>
<header>
<table class="headerTable">
<tr>
<td class="left"><p>Sample document</p></td>
<td class="middle"><p><strong>Docxpresso</strong></p></td>
<td class="right"><p>page <page/></p></td>
</tr>
</table>
</header>
<h1>Sample document</h1>
<p class="summary"><strong>Summary. </strong> This is a document created out from HTML5 and CSS code. 
The document includes a few standard document elements to better illustrate the package functionality.</p>
<h2>Some random content</h2>
<p>This is a paragraph where we are going to include a couple of elements. Here we include a 
footnote<footnote><span class="footnote">To include a footnote is as simple as this.</span></footnote> and also a link to
<a href="http://www.Docxpresso.com">Docxpresso</a> website.</p>
<p class="image"><img src="scene.jpg"/></p>
<h2>A nice table</h2>
<p>Let us include a nicely formatted table:</p>
<table class="nice">
<tr>
<th><p>First Column</p></th>
<th><p>Second Column</p></th>
<th><p>Third Column</p></th>
</tr>
<tr>
<td class="firstCol"><p>Row 1</p></td>
<td class="even"><p>C_1_1</p></td>
<td class="even"><p>C_1_2</p></td>
</tr>
<tr>
<td class="firstCol"><p>Row 2</p></td>
<td class="odd"><p>C_2_1</p></td>
<td class="odd"><p>C_2_2</p></td>
</tr>
<tr>
<td class="firstCol"><p>Row 3</p></td>
<td class="even"><p>C_3_1</p></td>
<td class="even"><p>C_3_2</p></td>
</tr>	
</table>
<h2>A nested list</h2>
<p>In order to finish the example a nested list: </p>
<ul>
<li>This item has a <strong>sublist</strong>:
<ul>
<li>Subitem 1.</li>
<li>Subitem 2.</li>
</ul>
</li>
<li>The final item.</li>
</ul>
</body>
</html>
';
//insert the HTML
$doc->html(array('html' => $html));
//include in the render method the path where you want your document to be saved
$doc->render('template_HTML' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'template_HTML' . $format . '">Download document</a>';  

DOWNLOAD:

Docxpresso API

<?php
/**
* This sample script generates a sample
* document out of HTML code
*/
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert the header
$headerCell = 'font-family: Arial; font-size: 10pt; border-bottom: 0.5pt solid #333; padding: 3px 7px;';
$doc->header()->style('height: 1.5cm')
->table(array('grid' => array('5cm', '8cm', '2cm')))
->row()
->cell()->style($headerCell)->style('background-color: #b74444')
->paragraph()->style('text-align: right; color: #ffffff; margin:0; background-color: #b74444')
->text(array('text' => 'Sample document'))
->cell()->style($headerCell)
->paragraph()->style('color: #333; font-weight: bold; margin: 0')
->text(array('text' => 'Docxpresso'))
->cell()->style($headerCell)
->paragraph()->style('text-align: right; color: #333; margin:0')
->text(array('text' => 'page '))
->field('page-number');
//insert the document title
$doc->heading(array('level' => 1))->style('font-family: Arial')
->text(array('text' => 'Sample document'));
//insert a a summary
$doc->paragraph()->style('font-family: Arial; font-size: 10pt; margin: 10pt 40pt; text-align: justify')
->text(array('text' => 'Summary. '))->style('font-weight: bold')
->text(array('text' => 'This is a document directly created with the Docxpresso public API. 
The document includes a few standard document elements to better 
illustrate the package functionality.'));
//insert some content
$doc->heading(array('level' => 2))->style('font-family: Arial;  margin: 25pt 0 5pt 0')
->text(array('text' => 'Some random content'));
$doc->paragraph()->style('font-family: Arial; font-size: 10pt; margin-bottom: 10pt')
->text(array('text' => 'This is a pragraph where we are going to include a couple of elements. '))
->text(array('text' => 'Here we include a footnote'))
->footnote()
->text(array('text' => 'To include a footnote is as simple as this.'))->style('font-size: 9pt; font-family: Arial')
->end('footnote')
->text(array('text' => ' and also a link to the '))
->link(array('url' => 'http://www.Docxpresso.com'))
->text(array('text' => 'Docxpresso'))
->end('link')
->text(array('text' => ' website.'));
$doc->paragraph()->style('text-align:center')
->image(array('src' => 'scene.jpg'));
$doc->heading(array('level' => 2))->style('font-family: Arial; margin: 25pt 0 5pt 0')
->text(array('text' => 'A nice table'));	
$doc->paragraph()->style('font-family: Arial; font-size: 10pt; margin-bottom: 10pt')
->text(array('text' => 'Let us include a nicely formatted table: '));
//insert a table
//first some styles
$firstRowCell = 'background-color: #5B9BD5; padding: 3px 7px';
$firstRowP = 'font-family: Arial; font-size: 10pt; color: #f6f6f6; background-color: #5B9BD5; font-weight: bold; font-size: 10pt; margin: 0';
$firstColCell = 'background-color: #5B9BD5; padding: 3px 7px; border: 0.5pt solid #ffffff';
$firstColP = 'font-family: Arial; font-size: 10pt;  color: #f6f6f6; background-color: #5B9BD5; font-weight: bold; font-size: 10pt; margin: 0';
$even = 'background-color: #BDD6EE; padding: 3px 7px; border: 0.5pt solid #ffffff';
$odd = 'background-color: #DEEAF6; padding: 3px 7px; border: 0.5pt solid #ffffff';
$evenP = 'font-family: Arial; font-size: 10pt; color: #333; background-color: #BDD6EE; font-size: 10pt; margin: 0';
$oddP =  'font-family: Arial; font-size: 10pt; color: #333; background-color: #DEEAF6; font-size: 10pt; margin: 0';
$doc->table(array('grid' => array('4cm', '4cm', '4cm')))->style('width: 12cm; margin:auto')
->row()
->cell()->style($firstRowCell)
->paragraph(array('text' => 'First column'))->style($firstRowP)
->cell()->style($firstRowCell)
->paragraph(array('text' => 'Second column'))->style($firstRowP)
->cell()->style($firstRowCell)
->paragraph(array('text' => 'Third column'))->style($firstRowP)
->row()
->cell()->style($firstColCell)
->paragraph(array('text' => 'Row 1'))->style($firstColP)
->cell()->style($even)
->paragraph(array('text' => 'C_1_1'))->style($evenP)
->cell()->style($even)
->paragraph(array('text' => 'C_1_2'))->style($evenP)
->row()
->cell()->style($firstColCell)
->paragraph(array('text' => 'Row 2'))->style($firstColP)
->cell()->style($odd)
->paragraph(array('text' => 'C_2_1'))->style($oddP)
->cell()->style($odd)
->paragraph(array('text' => 'C_2_2'))->style($oddP)
->row()
->cell()->style($firstColCell)
->paragraph(array('text' => 'Row3'))->style($firstColP)
->cell()->style($even)
->paragraph(array('text' => 'C_3_1'))->style($evenP)
->cell()->style($even)
->paragraph(array('text' => 'C_3_2'))->style($evenP);
$doc->heading(array('level' => 2))->style('font-family: Arial;  margin: 25pt 0 5pt 0')
->text(array('text' => 'A nested list'));	
$doc->paragraph()->style('font-family: Arial; font-size: 10pt; margin-bottom: 10pt')
->text(array('text' => 'In order to finish the example a nested list: '));
//include a nested list
$listItem = 'font-family: Arial; font-size: 10pt; margin-bottom: 5pt;';
$sublistItem = 'font-family: Arial; font-size: 10pt; font-style: italic; color: #555; margin-bottom: 5pt';
$doc->unorderedList()
->listItem()
->paragraph()->style($listItem)
->text(array('text' => 'This item has a '))
->text(array('text' => 'sublist' ))->style('font-weight: bold')
->text(array('text' => ':'))
->unorderedList()
->listItem()
->paragraph()->style($sublistItem)
->text(array('text' => 'SubItem 1'))
->listItem()
->paragraph()->style($sublistItem)
->text(array('text' => 'SubItem 2'))
->end('list')
->listItem()
->paragraph()->style($listItem)
->text(array('text' => 'The final item.'));
//include in the render method the path where you want your document to be saved
$doc->render('template_API' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'template_API' . $format . '">Download document</a>';

DOWNLOAD:

As you can check by the resulting documents one reproduces the same formatting using either HTML5 code or the public API so using one or the other is just a matter of choice or convenience.

We hope that by now we have already awakened your curiosity and you are willing to proceed with the rest of the documentation 🙂