pdx:addSimpleField Inserts a Word field into your Word document

pdx:addSimpleField

Inserts a Word field into your Word document.

Description

Element definition

<pdx:content>
    <pdx:addSimpleField pdx:fieldName="" pdx:fieldType="date|numeric|general" pdx:fieldFormat="" pdx:doNotShadeFormData="" pdx:updateFields="" pdx:wordFragmentName="">
        <pdx:paragraphStyle />
    </pdx:addSimpleField>
</pdx:content>

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 and
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 ommit 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

The possible keys and values are:

key	Description
pStyle	The WordML fragment object containing the contents for the even pages header
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).
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 we 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	1 corresponds to single line spacing, 2 to double line spacing and so long so forth. It admits decimal numbers.
pageBreakBefore	If true forces a page break before the paragraph.
rtl	Set to true for right to left languages like Hebrew or Arabic.
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
textAlign	Text alignment within paragraphs. 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.
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

<?xml version="1.0" encoding="UTF-8"?>
<pdx:document xmlns:pdx="http://www.phpdocx.com/main">
    <pdx:config>
        <pdx:output pdx:name="output" pdx:type="docx" />
    </pdx:config>
</pdx:document>

content.xml

<?xml version="1.0" encoding="UTF-8"?>
<pdx:document xmlns:pdx="http://www.phpdocx.com/main">
    <pdx:content>
        <pdx:addText>
            <pdx:textRun>
                <pdx:data pdx:dataId="" pdx:dataType="text">We add a few simple fields that render some properties:</pdx:data>
            </pdx:textRun>
        </pdx:addText>
        <pdx:addSimpleField pdx:fieldName="TITLE" pdx:fieldType="general" pdx:fieldFormat="" pdx:doNotShadeFormData="" pdx:updateFields="">
            <pdx:paragraphStyle />
        </pdx:addSimpleField>
        <pdx:addSimpleField pdx:fieldName="AUTHOR" pdx:fieldType="general" pdx:fieldFormat="" pdx:doNotShadeFormData="" pdx:updateFields="">
            <pdx:paragraphStyle />
        </pdx:addSimpleField>
        <pdx:addSimpleField pdx:fieldName="NUMPAGES" pdx:fieldType="general" pdx:fieldFormat="" pdx:doNotShadeFormData="" pdx:updateFields="">
            <pdx:paragraphStyle />
        </pdx:addSimpleField>
        <pdx:addSimpleField pdx:fieldName="COMMENTS" pdx:fieldType="general" pdx:fieldFormat="" pdx:doNotShadeFormData="" pdx:updateFields="">
            <pdx:paragraphStyle />
        </pdx:addSimpleField>
    </pdx:content>
</pdx:document>

settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<pdx:document xmlns:pdx="http://www.phpdocx.com/main">
    <pdx:settings>
        <pdx:addProperties>
            <pdx:title>The title of the document.</pdx:title>
            <pdx:creator>The autor of the document.</pdx:creator>
            <pdx:description>A description of the document.</pdx:description>
        </pdx:addProperties>
        <pdx:docxSettings>
            <pdx:updateFields pdx:value="true"/>
        </pdx:docxSettings>
    </pdx:settings>
</pdx:document>

import os as os
import sys as sys
sys.path.append(os.path.abspath("wrappers/python/XmlDocx"))
import XmlDocx as XmlDocx
document = XmlDocx.XmlDocx("config.xml")
document.setDocumentProperties("settings.xml")
document.addContent("content.xml")
document.setXmlDocxPath("xmldocx path")
document.render()

The resulting Word document looks like: