XML API - pdx:addSimpleField

pdx:addSimpleField

Inserts a Word field into your Word document.

Note

You are reading the XML API documentation. For the PHP API method please go to addSimpleField.

Description

Element definition

This element allows you to insert different types of Word fields into your Word document.

Among the automatic fields that you may insert are:

  • AUTHOR
  • COMMENTS
  • DOCPROPERTY
  • FILENAME
  • FILESIZE
  • KEYWORDS
  • LASTSAVEDBY
  • NUMCHARS
  • NUMPAGES
  • NUMWORDS
  • SUBJECT
  • TEMPLATE
  • TITLE

Beware that, of course, some of these fields (like, for example, AUTHOR) have to be previously defined in the Word document. This can be achieved either via the use of a customized base template or with the help of the addProperties element.

There are specific methods for the insertion of dates and page numbers that allow for a further customization of the resulting field. If the updateFields option is not set to true, in certain cases, the user may need to press F9 in the MS Word interface to update the field value. Please, check for each particular case in the resulting Word document.

Attributes and sub-elements

fieldName

Footer contents.

fieldType

The possible values are general (default), numerical or alphabetical.

fieldFormat

This requires a working knowledge of the Word simple fields available formats (see, for example, this web page). Beware that you should omit the \*, \# and the \@ chunks that are already taken into account in the type parameter. The default value is empty.

doNotShadeFormData

If true does not shade the corresponding field. Default value is false.

updateFields

If true the user will be prompted to update the field data on opening the Word document. Check case by case if you need to activate this property. The default value is false.

options

This is an array including all general paragraph wide options.

The possible keys and values of this array are:

Key Description
pStyle Word style to be used. Run parseStyles() method to check all available paragraph styles.
backgroundColor Hexadecimal color value: FF0000, 000000...
bidi Set to true for right to left languages like Hebrew or Arabic.
bold If true the text will be shown in bold characters.
border Available values are:
  • none (default)
  • double
  • dashed
  • outset
  • inset
  • threeDEmboss
  • threeDEngrave
You can access to the complete list in: Border Styles.
borderBottom Overwrites the general border type for the bottom border of the paragraph.
borderLeft Overwrites the general border type for the left border of the paragraph.
borderTop Overwrites the general border type for the top border of the paragraph.
borderRight Overwrites the general border type for the right border of the paragraph.
borderColor Hexadecimal color value: FF0000, 000000...
borderBottomColor Overwrites the general border color for the bottom border of the paragraph.
borderLeftColor Overwrites the general border color for the left border of the paragraph.
borderTopColor Overwrites the general border color for the top border of the paragraph.
borderRightColor Overwrites the general border color for the right border of the paragraph.
borderSpacing Separation between border and text in points.
borderBottomSpacing Overwrites the general border spacing for the bottom border of the paragraph.
borderLeftSpacing Overwrites the general border spacing for the left border of the paragraph.
borderTopSpacing Overwrites the general border spacing for the top border of the paragraph.
borderRightSpacing Overwrites the general border spacing for the right border of the paragraph.
borderWidth Border width in eigths of a point.
borderBottomWidth Overwrites the general border width for the bottom border of the paragraph.
borderLeftWidth Overwrites the general border width for the left border of the paragraph.
borderTopWidth Overwrites the general border width for the top border of the paragraph.
borderRightWidth Overwrites the general border width for the right border of the paragraph.
caps If true displays text in capital letters.
color Hexadecimal color value: 'FF0000', '000000'...
contextualSpacing If true ignores spacing above and below the paragraph whenever the neighbouring paragraphs use the same Word style (false by default).
doubleStrikeThrough If true displays text in doubleStrikeThrough.
em Emphasis mark type: 'none', 'dot', 'circle', 'comma', 'underDot'.
firstLineIndent First line indentation in twentieths of a point (twips).
font Font family: 'Arial', Calibri'...
fontSize Font size in points.
hanging Paragraph hanging in twentieths of a point (twips).
headingLevel The heading level if you want this paragraph to be a heading.
italic If true displays the text in italics.
indentLeft Left margin in points.
indentRight Right margin in points.
keepLines Keeps (whenever possible) all the current paragraph lines on the same page (default value is false).
keepNext Keeps (whenever possible) in the same page the current paragraph with next paragraph (default value is false).
lineSpacing 120, 240 (standard), 360, 480... (in twentieths of a point).
pageBreakBefore If true forces a page break before the paragraph.
position Position value. Positive value for raised and negative value for lowered.
rtl Set to true for right to left languages like Hebrew or Arabic.
scaling Scaling value, 100 is the default value.
smallCaps If true displays text in small capital letters.
spacingBottom Bottom padding in twentieths of a point.
spacingTop Top padding in twentieths of a point.
strikeThrough If true displays text in strikethrough.
tabPositions Each entry is an associative array with the following keys and values:
  • 'type' (string) can be clear, left (default), center, right, decimal, bar and num.
  • 'leader' (string) can be none (default), dot, hyphen, underscore, heavy and middleDot.
  • 'position' (int) given in twentieths of a point.
If there is a tab and the tabPositions array is not defined the standard tab position (default of 708) will be used.
textAlign Text alignment within paragraph. Possible values are: center, right, both and distribute.
textDirection Text flow direction within a table cell. Possible values are: lrTb, tbRl, btLr, lrTbV, tbRlV and tbLrV.
underline Underlines text. Possible values are: single, words, double, dotted, dash and wave.
underlineColor Underlines text with a color: 'FF0000', '000000'...
vanish Uses a vanish style.
widowControl Prevents Word from printing the last line of a paragraph by itself at the top of the page (widow) or the first line of a paragraph at the bottom of a page (orphan).
wordWrap Allows line breaking at character level (default value is false).
Code samples

Example #1

config.xml

content.xml

settings.xml

PHP code

The resulting Word document looks like: