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:

Signature

public field ($type [, $options])

Parameters

  • $type (type: string). The possible values are: author-name, bookmark-ref, date, page-count, page-number and title.
  • $options (type: array). This array has the following available keys and values:
    • date-format (type: string). The date field is built by running consecutively through the array entries. possible values are:
      • A character or string of text.
      • A day, month or year in the following formats:
        • day: day of the month with two digits.
        • day-short: day of the month with one/two digits (as required).
        • day-of-week: day of the week in textual format.
        • day-of-week-short: abbreviated day of the week in textual format.
        • month: month of the year with two digits.
        • month-short: month of the year with one/two digits (as required) .
        • month-of-year: month of year in textual form.
        • month-of-year-short: month of year in abbreviated textual form.
        • year: year number with four digits.
        • year-short: year number with 2 digits.
    • default-value (type: string). The field default value, if any.
    • number format (type: string, default: 1). Used for page-count and page-number types. The possible values are:
      • 1: Hindu-Arabic number sequence, it starts with 1.
      • a: number sequence of lowercase Modern Latin basic alphabet characters, it starts with 'a'.
      • A: number sequence of uppercase Modern Latin basic alphabet characters, it starts with 'A'.
      • i: number sequence of lowercase Roman numerals, it starts with 'i'.
      • I: number sequence of uppercase Roman numerals, it start with 'I'.
    • number-offset (type: integer). Allows to start the numbering with a given offset. For example, if we would like to ignore the front page for page numbering we should choose a value of -1.
    • reference-format (type: string). Used for the bookmark-ref option exclusively. The possible values are:
      • page: displays the number of the page on which the referenced item appears.
      • text: displays the text of the referenced item.
    • reference-name (type: string). The name of the linked reference. Used for the bookmark-ref option exclusively.
    • style (type: string). A string of styles in CSS format.

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 Docxpresso\CreateDocument();
$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:download pdfdownload docdownload docxdownload odtdownload rtf

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 Docxpresso\CreateDocument();
$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:download pdfdownload docdownload docxdownload odtdownload rtf

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 Docxpresso\CreateDocument();
$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:download pdfdownload docdownload docxdownload odtdownload rtf

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 Docxpresso\CreateDocument();
$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:download pdfdownload docdownload docxdownload odtdownload rtf

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