Fields

Fields in the context of Docxpresso represent automatic pieces of contents that are taken from the document layout, properties and metadata.

Docxpresso offers you the following set of fields to be inserted anywhere in your document (body, headers and footers, footnotes, etcetera):

• Comming from the document metadata:
  • Author name.
  • Document title.
• Layout dependent:
  • Page number.
  • Total page count.
  • Bookmark reference (page or text).
• System dependent:
  • Date.

The core method responsible of inserting a variable field in the document is the field method which public API is given by:

The relevant CSS style type styles that one may apply concide with the ones of the text method and we refer to them for further details (see Text)

The field variables are shown in Libre and Open Office with an ugly grey background that is not printed and its only purpose is to notify the user that that content has been automatically generated. The user may choose to deactivate that option in the interface but it is not an styling option and as such can not be deactivated beforehand.

Let us go over all the different type offering additional explanations when needed.

Dates

If you do not want to use your system default option regarding the date format you may choose a custom one via the date option.

Let us assume that you want a date in the following formats:

• ’07/03/2014′, then you should set the date-format option to: array(‘day’, ‘/’, ‘month’, ‘/’, ‘year’).
• ‘Thursday 7, November 2014’, the you need: array(‘day-of-week’, ‘ ‘, ‘day-short’, ‘, ‘ , ‘month-of-year’, ‘ ‘, ‘year’)

and so long so forth.

Let us work out an actual example:

<?php
/**
 * This sample script inserts a simple paragraph with a a date field
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph with a date field
$options = array('date-format' => array('month-short', '-' , 'day-short', '-', 'year'));
$doc->paragraph(array('text' => 'This document was generated the '))
        ->field('date', $options)
        ->text(array('text' => '.'));
//include in the render method the path where you want your document to be saved
$doc->render('date' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'date' . $format . '">Download document</a>';

DOWNLOAD:

Page numbering

Among all the possible uses of the field method this is probably the most common one.

Let us show here a simple scenario of use (you can also check the header and footer methods for other useful examples):

<?php
/**
 * This sample script inserts page numberings and page counts
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph with page number and total page count
$doc->paragraph(array('text' => 'This is page  '))
        ->field('page-number')
        ->text(array('text' => ' of a total of '))
        ->field('page-count')
        ->text(array('text' => ' pages.'));
//insert a paragraph with page number and total page count in a new page
$doc->paragraph(array('text' => 'This is page  '))->style('page-break-before: always')
        ->field('page-number')
        ->text(array('text' => ' of a total of '))
        ->field('page-count')
        ->text(array('text' => ' pages.'));
//include in the render method the path where you want your document to be saved
$doc->render('page_numbering' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'page_numbering' . $format . '">Download document</a>';

DOWNLOAD:

Bookmarks

Although of much less common use the bookmark-ref option can be of help when we want to refer by page or by content a bookmarked element of our document (cross-referencing).

Let us adapt one of our previous bookmark samples to this particular case:

<?php
/**
 * This sample script inserts a link in the first page that points (via its page number)
 * to a  bookmark in the second page
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph with a link to the page of the bookmarked paragraph
$linkData = array(
    'url' => '#myBookmark',  
    'title' => 'An internal cross-reference',
);
$refData = array('reference-name' => 'myBookmark', 'reference-format' => 'page');
$doc->paragraph(array('text' => 'This is a very simple paragraph with a link to bookmarked content in page '))
        ->link($linkData)->field('bookmark-ref', $refData)->end('link')
        ->text(array('text' => '.'));
//insert a paragraph with a bookmark in a new page
$doc->paragraph(array('style' => 'page-break-before: always'))
        ->bookmark(array('name' => 'myBookmark'))
        ->text(array('text' => 'This is the bookmarked paragraph.'));
//include in the render method the path where you want your document to be saved
$doc->render('bookmark_ref' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'bookmark_ref' . $format . '">Download document</a>';

DOWNLOAD:

This property is not fully supported in RTF format.

Authoring and title

Let us finish this topic by offering a sample script that includes title and authoring information. Beware that that info is taken from the document metadata so we have first to make sure that it exists either by including it explicitely in then document via the metadata method or because we use a template that already includes the required metadata.

<?php
/**
 * This sample script inserts author and title fields
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//first insert some metadata
$metadata = array('author' => 'William Shakespeare', 'title' => 'Hamlet');
$doc->metadata($metadata);
//Insert now a paragraph including those two fields
$doc->paragraph(array('text' => 'This is the original manuscript of '))->style('font-style: italic')
        ->field('title')->style('color: #b70000')
        ->text(array('text' => ' written by '))
        ->field('author-name')->style('color: #b70000; font-weight: bold')
        ->text(array('text' => ' the Bard of Avon.'));
//include in the render method the path where you want your document to be saved
$doc->render('authoring' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'authoring' . $format . '">Download document</a>';

DOWNLOAD:

Beware that there are currently some limitations in the field styles inheritance in .docx format.