Tables are usually an essential component of a technical document, business report or commercial presentation.

If you want to insert anything but a vary basic table with Docxpresso you will need to use the table, row and cell core methods that now we pass to describe in detail.

Table

The core method responsible of inserting a table is the table method which public API is given by:

Signature

public table ([$options])

Parameters

  • $options (type: array). This array has the following available keys and values:

    • table-content (type: array). an optional array of arrays with the values to be included in the different table rows and cells. Each final entry may be an string of text or a document fragment. Beware that you can get higher control by including the table contents via the row and cell methods.
    • grid (type: mixed, default: 1). It may be:
      • The number of columns (integer): all columns are of equal size.
      • An array where each item represents the respective column width.
    • mask (type: array). This arraysets the table theme options that should be applied to the current table (it only applies if a theme is loaded). The default values are: array(‘NE’=>true, ‘NW’=>true, ‘SE’=>true, ‘SW’=>false, ‘firstRow’=>true, ‘lastRow’=>false, ‘bandedRow’=>true, ‘firstCol’=>true, ‘lastCol’=>false, ‘bandedCol’=>false)
    • style (type: string). A string of styles in CSS format.

The relevant CSS style type styles that one may apply to a table include (where ‘*’ in this context stands for top, right, bottom or left).

  • Background:
    • background: shorthand for background properties.
    • background-color: sets the background color.
    • background-image: sets the background image.
    • background-position: sets the position of the background image.
    • background-repeat: specifies if the background image will repeat or not.
  • Structural:
    • page-break-before: specifies if a page break should occur before the paragrah.
    • page-break-after: specifies if a page break should occur after the paragrah.
    • page-break-inside: specifies if a page break is allowed within the paragraph.
  • Size and Margins:
    • width: the total table width.
    • margin: specifies all margin widths in on shot.
    • margin-*: specifies one margin at a time.
  • Other:
    • border-collapse: sets the table border model.
    • direction or writing-mode: sets the text direction.

A couple of comments are now due:

  • Although you can directly set global table borders when using directly the html method with HTML code, there is no direct way to set borders at the table level using the table style option. This is so because they are implemented at the cell level to gain maximum versatility.
  • If you wish to float a table you need to create first a textbox (see textboxes for further details) and include the table within. You may also obtain a similar layout effect with nested tables.

Row

The core method responsible of inserting a table row is the row method which public API is given by:

Signature

public row ([$options])

Parameters

  • $options (type: array). This array has the following available keys and values:

    • header (type: boolean, default: false). If true it is a header row. If a table spans through more than one page the header rows are repeated at the beginning of each new page.
    • row-content (type: array). An optional array with the row contents. Each array item may be a string of text or a document fragment. Beware that you may have higher control by using the cell method to insert content into a row.
    • style (type: string). A string of styles in CSS format.

The relevant CSS style type styles that one may apply to a table row include:

  • Background:
    • background: shorthand for background properties.
    • background-color: sets the background color.
    • background-image: sets the background image.
    • background-position: sets the position of the background image.
    • background-repeat: specifies if the background image will repeat or not.
  • Structural:
    • page-break-before: specifies if a page break should occur before the paragrah.
    • page-break-after: specifies if a page break should occur after the paragrah.
    • page-break-inside: specifies if a page break is allowed within the paragraph.
  • Size:
    • height: the table row height.
    • min-height: the minimum table row height.

Cell

The core method responsible of inserting a table cell is the cell method which public API is given by:

Signature

public cell ([$options])

Parameters

  • $options (type: array). This array has the following available keys and values:

    • cell-content (type: mixed). The cell content may be a string of text or a document fragment. Beware that you may include arbitrary content by chaining.
    • colspan (type: integer, default: 1).
      the number of columns that the table cell should cover.
    • rowspan (type: integer, default: 1). The number of rows that the table cell should cover.
    • style (type: string). A string of styles in CSS format.

The relevant CSS style type styles that one may apply to a table cell include:

  • Background:
    • background: shorthand for background properties.
    • background-color: sets the background color.
    • background-image: sets the background image.
    • background-position: sets the position of the background image.
    • background-repeat: specifies if the background image will repeat or not.
  • Borders:
    • border: shorthand for border properties.
    • border-color: sets the border color.
    • border-style: sets the border line style.
    • border-width: sets the border width.
    • border-*-color: sets only the border color of one side.
    • border-*-style: sets only the border line style of one side.
    • border-*-width: sets only the border width of one side.
  • Alignment:
    • vertical-align: specifies the vertical alignment of text.
  • Cell paddings:
    • padding: specifies all padding widths in on shot.
    • padding-*: specifies one padding at a time.
  • Other:
    • direction or writing-mode: sets the text direction.

Notice that the text styling options should be set at the cell content method whenever using the core Docxpresso methods.

Code samples

Basic example

Let us start by building a simple table with some formatting:

<?php
/**
 * This sample script inserts a simple table
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//inserts a table
//styles for the first row
$firstRowCell='border: 2px solid red; background-color: #b70000; padding: 1px 9px;';
$firstRowText='font-weight: bold; color: white; font-size: 13px; font-family: Verdana; margin: 3px;';
//normal row style
$standardCell='border: 1px solid #555555; padding: 1px 9px';
$leftText='font-size: 12px; font-family: Arial; font-weight: bold; color: #444444; margin: 3px';
$rightText='font-size: 12px; font-family: Arial; text-align: right; margin: 3px';
//insert the table
$doc->table(array('grid' => 2))
        ->row()
            ->cell()->style($firstRowCell)
                ->paragraph(array('text' => 'Item Name'))->style($firstRowText)
            ->cell()->style($firstRowCell)
                ->paragraph(array('text' => 'Price($)'))->style($firstRowText)->style('text-align: right')
        ->row()
            ->cell()->style($standardCell)->style('background-color: #f0f0f0')
                ->paragraph(array('text' => 'First item'))->style($leftText)
            ->cell()->style($standardCell)
                ->paragraph(array('text' => '356.45'))->style($rightText)
        ->row()
            ->cell()->style($standardCell)->style('background-color: #f0f0f0')
                ->paragraph(array('text' => 'Second item'))->style($leftText)
            ->cell()->style($standardCell)
                ->paragraph(array('text' => '145.33'))->style($rightText);
//include in the render method the path where you want your document to be saved
$doc->render('simple_table' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_table' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

Beware that the default rendering of the table layout is different in Word documents that in other formats:
– PDF, ODT and RTF use by default all avalaible space when the table and/or column dimensions are not specified.
– Word (.doc) takes the minimally required space to fit the table contents.

In order to achive the same results in all formats one should, for example, include a fix grid and center the table, explicitely specifiyng size and positioning:

<?php
/**
 * This sample script inserts a simple centered table with fixed column width
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//inserts a table
//styles for the first row
$firstRowCell='border: 2px solid red; background-color: #b70000; padding: 1px 9px;';
$firstRowText='font-weight: bold; color: white; font-size: 13px; font-family: Verdana; margin: 3px;';
//normal row style
$standardCell='border: 1px solid #555555; padding: 1px 9px';
$leftText='font-size: 12px; font-family: Arial; font-weight: bold; color: #444444; margin: 3px';
$rightText='font-size: 12px; font-family: Arial; text-align: right; margin: 3px';
//insert the table
$doc->table(array('grid' => array('4cm', '4cm')))->style('margin: auto')
		->row()
			->cell()->style($firstRowCell)
				->paragraph(array('text' => 'Item Name'))->style($firstRowText)
			->cell()->style($firstRowCell)
				->paragraph(array('text' => 'Price($)'))->style($firstRowText)->style('text-align: right')
		->row()
			->cell()->style($standardCell)->style('background-color: #f0f0f0')
				->paragraph(array('text' => 'First item'))->style($leftText)
			->cell()->style($standardCell)
				->paragraph(array('text' => '356.45'))->style($rightText)
		->row()
			->cell()->style($standardCell)->style('background-color: #f0f0f0')
				->paragraph(array('text' => 'Second item'))->style($leftText)
			->cell()->style($standardCell)
				->paragraph(array('text' => '145.33'))->style($rightText);

//include in the render method the path where you want your document to be saved
$doc->render('simple_table_centered' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_table_centered' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

If you prefer to assign percentages in the grid you should set the total width in order to get reliable results. Beware that by the time being the support of relative column widths in Docxpresso for .doc is incomplete.

Header rows and banded rows

Let us now slightly modified the previous example in order to create a very long table that spans more than one page.

If we want to achieve optimal results we should add some extra formatting:

  • Declare the first row as header so it repeats at the beginning of each page.
  • Use banded rows so the contents are more easily scanned.
  • Make sure that rows are not broken across pages.

All of this can be easily achieved by this code:

<?php
/**
 * This sample script inserts a simple centered table with header and banded rows
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//inserts a table
//styles for the first row
$firstRowCell='background-color: #b70000; padding: 2px 9px;';
$firstRowText='font-weight: bold; color: white; font-size: 13px; font-family: Verdana; margin: 3px;';
//banded row style
$bandedRow = array('', 'background-color: #f0f0ff');
$standardCell='padding: 2px 9px';
$leftText='font-size: 12px; font-family: Arial; font-weight: bold; color: #444444; margin: 3px';
$rightText='font-size: 12px; font-family: Arial; text-align: right; margin: 3px';
//insert the table
$table = $doc->table(array('grid' => array('6cm', '4cm')))->style('margin: auto')
            ->row(array('header' => true))
                ->cell()->style($firstRowCell)
                    ->paragraph(array('text' => 'Item Name'))->style($firstRowText)
                ->cell()->style($firstRowCell)
                    ->paragraph(array('text' => 'Price($)'))->style($firstRowText)->style('text-align: right');
for ($j = 0; $j < 100; $j++){
      $table->row(array('style' => 'page-break-inside: avoid'))->style($bandedRow[$j%2])
                ->cell()->style($standardCell)
                    ->paragraph(array('text' => 'Item:' . $j))->style($leftText)
                ->cell()->style($standardCell)
                    ->paragraph(array('text' => rand(0, 99) . '.' . rand(10,99)))->style($rightText);
}
//include in the render method the path where you want your document to be saved
$doc->render('simple_table_header_banded' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_table_header_banded' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

Word and RTF format does not directly support background-color for rows, nevertheless you may easily achieve the same result applying the "bandedRow" style to the cells belonging to odd rows.

Column and row spans

It is pretty common need that a particular table cell covers more than one column or row, Docxpresso offers the freedom to do so by a judicious use of the rowspan and colspan cell options

A particular example of a table that use the above options is given by:

<?php
/**
 * This sample script inserts a simple centered table with col and row spans
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph
$doc->paragraph(array('text' => 'A table with col and row spans: '));
//inserts a table
//styles for the different cells
$rightCell = 'background-color: #f0f0f0; padding: 4px 9px 0 9px; border: 1px solid #999999;';
$leftCell = 'background-color: #fffff0;padding: 4px 9px 0 9px; border: 1px solid #999999;';
//insert the table
$doc->table(array('grid' => array('4cm', '6cm')))->style('margin: auto')
        ->row()
            ->cell(array('rowspan' => 2))->style($leftCell)
                ->paragraph(array('text' => 'A row span of 2'))
            ->cell()->style($rightCell)
                ->paragraph(array('text' => 'Some text'))
        ->row()
            ->cell()->style($rightCell)->style('background-color: #f0f0ff')
                ->paragraph(array('text' => 'Some other random text'))
        ->row()
            ->cell(array('colspan' => 2))->style($rightCell)->style('background-color: #fff0f0')
                ->paragraph(array('text' => 'A cell spanning two columns'))
        ->row()
            ->cell(array('rowspan' => 2))->style($leftCell)
                ->paragraph(array('text' => 'Another row span of 2'))
            ->cell()->style($rightCell)
                ->paragraph(array('text' => 'A sample test'))
        ->row()
            ->cell()->style($rightCell)->style('background-color: #f0f0ff')
                ->paragraph(array('text' => 'Some other sample text'));
//include in the render method the path where you want your document to be saved
$doc->render('simple_table_col_row_span' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_table_col_row_span' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

Nested tables

There is a priori no limit in Docxpresso with respect to the nesting of tables.

Whenever you add content to a table by chaining (our prefered option a you have already probably guessed from our earlier examples) you should instruct your script that you have finished a (sub)table by the use of the end method as illustrated in the following example:

<?php
/**
 * This sample script inserts a table with a nested table
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph
$doc->paragraph(array('text' => 'A table with col and row spans and a nested table: '));
//inserts a table
//styles for the different cells
$rightCell = 'background-color: #f0f0f0; padding: 4px 9px 0 9px; border: 1px solid #999999;';
$leftCell = 'background-color: #fffff0;padding: 4px 9px 0 9px; border: 1px solid #999999;';
//insert the table
$doc->table(array('grid' => array('4cm', '6cm')))->style('margin: auto')
        ->row()
            ->cell(array('rowspan' => 2))->style($leftCell)
                ->table(array('grid' => array('2cm', '2cm')))
                    ->row()
                        ->cell()->paragraph(array('text' => 'One'))
                        ->cell()->paragraph(array('text' => 'Two'))
                    ->row()
                        ->cell()->paragraph(array('text' => 'Three'))
                        ->cell()->paragraph(array('text' => 'Four'))
                    ->end('table')//finish the subtable
            ->cell()->style($rightCell)
                ->paragraph(array('text' => 'Some text'))
        ->row()
            ->cell()->style($rightCell)->style('background-color: #f0f0ff')
                ->paragraph(array('text' => 'Some other random text'))
        ->row()
            ->cell(array('colspan' => 2))->style($rightCell)->style('background-color: #fff0f0')
                ->paragraph(array('text' => 'A cell spanning two columns'))
        ->row()
            ->cell(array('rowspan' => 2))->style($leftCell)
                ->paragraph(array('text' => 'Another row span of 2'))
            ->cell()->style($rightCell)
                ->paragraph(array('text' => 'A sample test'))
        ->row()
            ->cell()->style($rightCell)->style('background-color: #f0f0ff')
                ->paragraph(array('text' => 'Some other sample text'));
//include in the render method the path where you want your document to be saved
$doc->render('nested_table' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'nested_table' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

The generation of RTF by Docxpresso does not currently support nested tables.

Tables for layout

Although Docxpresso offers you multiple options to obtain complex layouts: floating elements, columns, text-boxes, etcetera, sometimes it may be faster and easier to use an old-fashiones table to obtain the desired output.

Let us close this section by just offering an example to this regard:

<?php
/**
 * This sample script inserts a table for layout purposes
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert the contents
$doc->paragraph(array('text' => 'A table used for layout: '));
$doc->table(array('grid' => array('6cm', '9cm')))
        ->row()->style('min-height: 3cm')
            ->cell()
                ->image(array('src' => 'html52pdf.png'))
            ->cell()
                ->paragraph()
                    ->text(array('text' => 'Some text to the '))
                    ->text(array('text' => 'right '))->style('font-weight: bold')
                    ->text(array('text' => 'of this image.'));
$doc->paragraph(array('text' => 'A final paragraph.'));
//include in the render method the path where you want your document to be saved
$doc->render('tables_for_layout' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'tables_for_layout' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf