Advanced Template Formats

The contents of a data source are made available by placeholders in a Word 2007 document. Change to the design mode to make all placeholders visible. There are placeholders that influence the structure of the document and placeholders replaced by the content(s) from the data source.

The following actions can be performed with the placeholders:

Insert a single value
Insert a list
Insert an image
Conditional omission, insertion or formatting of another tag: Conditions
Side and column breaks
and much more.

The desired behavior is determined on the one hand by the type of the placeholder and on the other by the name of the tag (ie the name of the XML node in the XML output). In the Word templates, the following default content controls can be used as placeholders from the Developer Tools tab:

Rich Text Content Control
Plain Text Content Control
Picture Content Control

In general, Rich Text and Text controls are used for textual content and control characters. For image content controls, the value from the data source is interpreted as a URL or as a Base64-encoded data stream, and the image is inserted at the placeholder. For textual controls, the textual content is inserted accordingly. Placeholders, images, and text retain their formatting after they are replaced. On which nodes in the data source a placeholder refers or which control information is applied determines the property Tag of the placeholder.

Tag Example

The "Payment Terms" text is replaced by the contents of the Rich Text control tags paymenttermscode when creating documents. That There is a node of the same name in the XML output and a field of the same name in the requested data record. If the field of the record is empty or there is no node with that name in the XML output, the entire tag is ignored.

Conventions for DataSources

A content agreement regarding the XML data structure between any data source and the implementation of the engine allows the right data to be inserted in the correct place in the document. The convention describes which control element refers to which node in the document.

Structural requirements for the XML structure

All XML output tags must be in the default namespace, and the top node must be named data. All other content is structured as follows.

<?xml version="1.0" encoding="utf-8"?>
<data>
    …
</data>

Simple Values

The name specified in the tag refers to a tag of the same name within the XML stream in the current context. If there is no context switch (see next section) to the data node.

<?xml version="1.0" encoding="utf-8"?>
<data>
    <nodea> Wert  von nodea</nodea>
    <nodeb> Wert  von nodeb</nodeb>
    …
</data>

Inside the document, the content of the placeholder is replaced by the value of the node.

Switching Context

Dependent data can be separated by contexts in order to avoid name conflicts. Context changes must start with a large letter and can not end with a 's'. The nesting depth is arbitrary.

<?xml version="1.0" encoding="utf-8"?>
<data>
    <nodea> Wert </nodea>
    <nodeb> Wert</nodeb>

    <Neuerkontext>
        <nodea>Wert</nodea>
        <nodeb> Wert </nodeb>   
    </Neuerkontext>
</data>

Lists

Enumerations of elements must start with a large letter and end with a small, s' end. The elements must bear the same name without the 's' at the end. (The 's' is appended automatically when several records are output, see DataSet Essential Attributes MultipleItems.)

Data structures of this form can be rendered as lists within an output document:

<Contacts>
    <Contact>
        <firstname>Rudolf</firstname>
        <lastname> Schneider</lastname>
    </Contact>
    <Contact>
        <firstname>Inge</firstname>
        <lastname> Schneider</lastname>
    </Contact>
</Contacts>

For each iteration, a context switch is automatically performed in the child nodes. The data nodes are then directly available in the document within the enumeration.

For example, if you want to display all contacts of an account with their firstname and lastname use the following structure:

Tag nesting example

This generated a document as follows:

Contact list example

If you insert the tags behind a bullet as given above, this bullet symbol is repeated for every new child tag (in our example for every Contact node).

Tip 1

Nesting a Rich Text Content Control within another placeholder you may need to copy and paste the inner placeholders into the outer content control. This means for the mentioned example that you would have to create the firstname and lastname placeholders at first and cut and paste them into the outer Contacts placeholder afterward.

Tip 2

In case Tip 1 does not give the desired results you can also try to create the inner placeholders first and the outer content control around them. You can do so by selecting the inner content controls and clicking Rich-Text. The Rich-Text content control should automatically form around the selected inner controls.

Nested Elements

If you are asking yourself why you should need nested content controls, the answer is: Because subordinate record sets are represented by nested XML tags in the XML Data Source.

Subordinate Xml

expand or collapse

You can expand or collapse the XML tag tree by clicking on the +/- symbols beside the tags. This simplifies the data structure.

Control Information

Rich-Text and Text content controls with the folowing Tagname have a special meaning: - Condition: - Removes the included content if the XPath condition specified in the Title property is not met. - Relative XPath expressions refer to the currently active data context. - The negation of the result set can be achieved by an "!" at the beginning of the XPath expression. - PageBreak: Inserts a page break

Conditions

Conditions are meant to hide or show content controls depending on CRM field values. The data contents of the condition control will be displayed only in case the concerning condition is fulfilled. Conditions are formulated in so-called XPath expressions. (Contact your system administrator for more detailed information.) For instance, to display the account name only in case the company resides in Switzerland, do the following:

First of all create an inner placeholder for the account name, hence .
Then insert the superordinate content control which holds the condition and edits its properties.
Condition controls always have the keyword ‚Condition‘ inside the Tag field. (consider capitalization rules!)
In the field ‚Title‘ you insert the expression for the condition: address1_country[text() = 'Switzerland']
Finally, you copy the inner placeholder into the condition control.

Condition Content Control Property view

Condition as Titel sample

XPath Expressions for Conditions

Example for XML output:

<Knotenname attribute=“blau“>
    <Unterknotenname alsoanattribute=“scharf“ andafurtherattribute=“weich“>Wert</Unterknotenname>
</Knotenname>

XPath expressions address the nodes of an XML document using a syntax similar to addressing directory trees. Subsequently is a list of sample expressions which is exhaustive with regard to its use inside Microsoft Word. If you need functions and calculations you have to use XPath expressions inside the Data Source.

Basic Syntax

Expression	Example	Comment
nodename	Title: `nodename` Tag: `Condition`	Addresses all nodes with this name ("nodename") .The shown condition hdies the data content of the condition controls oin case the node doesn't exist.
/	Title: `/nodename/subnodename` Tag: `Condition`	Starts the reference from the root node
@	Title: `nodename/@attribute` Tag: `Condition`	Address attributes, here the attribute with the name `attribute` within node `nodename`.
name/text()	Title: `nodename/text()` Tag: `Condition`	Select the value fo the node `name` interpreted as textual content.
name[expresssion]	Title: `name[text() != '']` Tag: `Condition`	Selects the node `name` in case the condition in square brackets holds true. In the example the textual content of the node mustn't be empty.
name[expression]	Title: Tag: `Name[@attribute = 'blue']`	Displays the value of the node only in case the expression returns true, thus in the given example its attribute `@attribute` equals `blue`.

Operators

Operator	Example	Comment
\|	`Name \| Name2`	Selects both nodes Name1 and Name2.
=	`@attribute = blue`	True in case the left and right expression are equal.
!=	`text() != 'unwandted'`
>	`number(text()) > 5`	True in case the left expression is greater than right expression. Here the textual content is converted to a number before comparison by the function `number()`.
<	``	less than
>=	``	greater or eqaul
<=	``	less or equal
or	`text() = 'String1' or text() = 'String2'`	Boolean logical OR. True in case the left or the right expression or buth are true.
and	`number(text()) != 3 and` `number(text()) != 5`	Boolean logical AND. True in case the left and right side return true.

xPath Version

Please note that the available functions are dependent on XPath version (1.0 or 2.0) currently supported by Microsoft.2 Furthermore a function within a content control is not able to address all tags in the XML source but just the node selected by the control. This results in restrictions which can only be solved by providing the needed functionality one level deeper in the data source.

Generate dynamic file names

The name of the document is generated by the /data/name node. The suffix is automatically added according to the document type.

<?xml version="1.0" encoding="utf-8"?>
<data>
    <name>Meine Datei</name>
    …
</data>

The document title is set by XSLT:

<xsl:template match="/data">
      <data>
            <name>
                <xsl:value-of select="fieldname" />
            </name>
            …
            <xsl:apply-templates />
      </data>
</xsl:template>

Set document properties

Document properties are generated from the /data/DocumentProperties node:

<?xml version="1.0" encoding="utf-8"?>
<data>
    <DocumentProperties>
        <title>Mein Titel</title>
        <description>Meine Beschreibung</description>
        …
    </DocumentProperties>
    …
</data>

The following document properties are available; - title - subject - creator - keywords - category - description

Example: Set DataName and DocumentProperties in the DataSource

<xsl:template match="/data">
    <data>         
            <name><xsl:value-of select="quotenumber" /></name>
        <DocumentProperties>
                <title>Angebot <xsl:value-of select="quotenumber" /></title>
                <subject>Angebot <xsl:value-of select="quotenumber" /></subject>
                <creator><xsl:value-of select="CallingUser/fullname" /> (awisto business solutions GmbH)</creator>
                <keywords>CRM,PDF,<xsl:value-of select="quotenumber" /></keywords>
                <description><xsl:value-of select="quotenumber" /></description>
                <category>CRM</category>
            </DocumentProperties>
        <xsl:apply-templates />
    </data>
</xsl:template>

Engine configuration possibilities

Settings can be specified via a configuration file of the engine according to the following scheme.

<WordSettings>
    <Settings>
        <Setting Key="<Name der Einstellung>" Value="<Wert>" />
    </Settings>
</WordSettings>

The following settings are available at this time:

Setting	Description	Value Range
AuthenticateImageDownload	Determines whether access to image resources is performed anonymously or in the process context of the server.	True, False
FullParagraphGenerationMode	Determines when and if sales changes are generated. If the value is True, then two successive line breaks lead to a section change. A line break always leads to a simple line break.	True, False
CleanupTags	Determines whether all tags are removed after application to the data source.	True, False
default value is bold