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.
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>
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.
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>
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).
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.
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.
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.
You can expand or collapse the XML tag tree by clicking on the +/- symbols beside the tags. This simplifies the data structure.
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 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.
|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.|
|Starts the reference from the root node|
|Address attributes, here the attribute with the name
|Select the value fo the node
|Selects the node
|Displays the value of the node only in case the expression returns true, thus in the given example its attribute
||Selects both nodes Name1 and Name2.|
||True in case the left and right expression are equal.|
||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
|>=||``||greater or eqaul|
|<=||``||less or equal|
||Boolean logical OR. True in case the left or the right expression or buth are true.|
||Boolean logical AND. True in case the left and right side return true.|
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:
|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|