The third and final step when using DocumentData to set up an integration to an external system, will be to output data from the DocumentData plugin to the document itself. To learn more about DocumentData and the data flow, read the basics.
Contents
General info [Back to top]
Unlike the Fetch and Transform steps, the output step configuration does not happen in the module, but rather in the document or presentation intended to receive data, i.e. the template.
The configuration varies slightly from application to application and this article will be divided into sections reflecting this.
One element is fairly consistent across platforms, however. This element being the bindings used to refer to the values produced in the transform step.
Bindings [Back to top]
Written in JSON syntax, the bindings can be configured to control various aspects of data insertion.
Following tag is the syntax when using DocumentData. The syntax is global, but it is the data that determines what should happen. This means, you should always use this tag and specify it in proportion to what should happen and with which integration. In this way, DocumentData can be described as a "language" that can be adjusted to many different integrations.
The tag string might seem familiar to configures of Templafy templates:
{"SkabelonDesign":{"type":"x","ignoreBlank":"x","binding":"x.x","format":"x","visibility":{"action":"x","binding":"x","operator":"x","compareValues":[""]}}}
The syntax of the DocumentData tag string is built on the syntax of the Templafy tag string. Lets break it down:
type (required)
Type can be either "Text", "Date" or "Group". Groups are used to control visibility of multiple content controls.
binding (required, except for group)
Binding refers to the binded key. We support the following prefixes.
Doc.ContentControl.x
Get string data of content control by name of x based on the range inside.
Doc.Prop.x
Get the string data of document property by name of x based on the text value.
Doc.Prop.BuiltIn.x
Get the string data of a built-in document property by name of x based on the text value.
Doc.CustomXml.x
Based on information inside the documentManagement element (xml), found inside the openXml of the document inside CustomXml\item(0...N).xml. Keys are based on the element hierarchy, e.g.: Doc.CustomXml._dlc_DocIdUrl.Description, where Description is a child of _dlc_DocIdUrl which is a child of the documentManagement element.
Doc.DateTime.Today
Get todays date. This will only work if type in binding is set to "Date".
Any other prefix
Others are based on dynamic data from other plugins. These may be defined as appropriate for the configuration.
ignoreBlank (applies only to text binding value)
Define this property to be true in the content control tag. This makes sure that a blank value will not bind the text if empty.
format (only valid for "type":"Date")
Refers to the date format used, e.g. yyyy-dd-mm.
visibility (optional)
Used if the content control needs to have the "visibility" changed based on some comparison.
action
Required if visibility is present. Can be either "Hide", "Show", "Keep" or "Delete". This value determines the action that will be triggered when the condition in binding, operator and compareValues are met.
binding
Required if visibility is present. Same as binding above as it controls the basis for comparison.
operator
Required if visibility is present. Controls the type of comparison and can be "Equals", "Contains", "StartsWith" or "EndsWith".
compareValues
Required if visibility is present. List of values that will be used for comparison. Used as or when comparing, thus if one of the values evaluates to true, the comparison evaluated to true.
Example of a typical binding
A typical binding with DocumentData in Word, is to have a content control that only shows when there is data in it.
{"SkabelonDesign":{"type":"Text","binding":"SekretaerDiverse1","visibility":{"action":"Show","binding":"SekretaerDiverse1","operator":"Equals","compareValues":[""]}}}
In this case, "SekretaerDiverse1" is the binding from DocumentData, which only shows in the document if there is any data. In a case where you read from a SQL database, this binding can be useful if there is not data in part of the query.
Reading the binding, it might be counter intuitive that the visibility says "action":"Show","binding":"SekretaerDiverse1","operator":"Equals","compareValues":[""] , but it should not be understood to only show if there is no value, as a Templafy binding would. Instead it should be understood as to show when there is a string value returned. If there was no data to insert, it would return null which is not a string value.
Connectors [Back to top]
There are several integrations that can be referred to in bindings without first being defined in DocumentData during the transform step. When using one of these connectors, simply add the corresponding prefix. Our different connectors are listed below with their prefixes:
-
Document properties:
Doc.Prop.[name] - Content controls:
Doc.ContentControl.[name] -
XML Parts:
Doc.CustomXml.[name] -
iManage:
IMan.[name] -
Sbsys:
Sbsys.[name] -
Netdocuments:
nd.[name] -
Outlook:
Outlook.[value]
Word [Back to top]
When we configure documents to receive data from DocumentData, we utilize ContentControls. Earlier in this article we discussed how to configure Bindings. These bindings are inserted in the Tag value of the ContentControl properties.
There are almost infinite ways to utilize various BaseExtensions commands as well as native Word tinkering to manipulate the ContentControls.
PowerPoint [Back to top]
In PowerPoint, we use the Alt text description and it must contain the Textual structure inside a JSON and/or shape value. Use syntax below in Alt text description:
{"SkabelonDesign":{"textualValue":"x","bindingCollection":{"x":{"SkabelonDesign"{"type":"x","binding":"x"}}}}}
In the syntax above, textualValue could also be shapeValue.
shapeValue controls the visibility and text of the shape, while textualValue only controls the visibility and string value inside. Here, shapeValue overrules textualValue with the text content (if both are used).
When we configure presentations to receive data from DocumentData, we utilize Alternative Text of shapes. Earlier in this article we discussed how to configure Bindings. These bindings are inserted in the Alternative Text.
{
"SkabelonDesign": {
"textualValue": "<key1/>",
"bindingCollection": {
"key1": {"SkabelonDesign":{"type":"x","ignoreBlank":"x","binding":"x.x","format":"x","visibility":{"action":"x","binding":"x","operator":"x","compareValues":[""]}}}
}
}
}
Inserting images
It is also possible to insert images in shapes using DocumentData. When doing so, instead of defining a textualValue, you must define an imageValue. To do so, add the following json config to the Alt text of the image placeholder:
{
"SkabelonDesign": {
"imageValue": "image.url",
"imageFill": true
}
}
The binding in imageValue is the binding to the path of the image to be inserted. imageFill controls whether the image should be inserted as fill of fit. Default is fit.
Define data to be bold
We support defining some data to be bold within the alternative text. Notice that this only possible for textualValue.
Use the <b></b> tag to define the text within to be bold. This works on both strings and keys. Here is an example:
{
"SkabelonDesign": {
"textualValue": "
<key1>
<b><s><![CDATA[Office: ]]></s></b><key1/>
</key1>
<s><![CDATA[
]]></s>
<key2>
<b><key2/></b><s><![CDATA[ ]]></s><key3/><s><![CDATA[, ]]></s><key4/>
</key2>,
"bindingCollection": {
"key1": {"SkabelonDesign":{"type":"Text","binding":"CVPartner.office.name"}},
"key2": {"SkabelonDesign":{"type":"Text","binding":"CVPartner.educations[0].year_to"}},
"key3": {"SkabelonDesign":{"type":"Text","binding":"CVPartner.educations[0].degree}},
"key4": {"SkabelonDesign":{"type":"Text","binding":"CVPartner.educations[0].school}}
}
}
}
Update specific slide
A presentation can contain several slides to be updated, but sometimes it can be handy to be able to update just one of them. Therefore, we are able to specify which slide that must be updated.
This is the command for updating a specific slide:
<Cmd case="SkabelonDesign.DocumentData:UpdateSlide" slideIndex="x"/>
In the parameter slideIndex, the slide index must be defined. The function will be counting, which means that if the second slide in a presentation is the one to be updated, write 2 in the parameter. Though, there is an option of counting from the back. To do so, insert ^ in front of the number value in the parameter. This means, if the parameter is defined to "^2", the second last slide in the presentation will be updated.
Define type of line break
If the data that should be inserted contains line breaks, we are able to define the type of line break within the alt text using the parameter lineBreakType that supports two options: Paragraph (default) and Soft. The parameter is optional and should only be applied when it is actually used.
Here is an example:
{
"SkabelonDesign": {
"textualValue": "<s>asd \r\n aswqe \r\n qwewqe </s>"
},
"lineBreakType": "Soft"
}
In client solutions, we often see a more advanced case, where the textual value refers to keys that are defined in the binding collection. Below is an example from a client where we use DocumentData to fetch data from CV Partner.
In this example, we fetch the data from the project experience section, where each key often contains a line break between content. The data should be inserted into a placeholder with bullets as indentation.
With the default set up (paragraph line breaks), the functionality will apply a bullet for each line break, which means that there will not only be a bullet for each key, but also for each section within a key. We thus use the soft line breaks to prevent this and ensure that bullets will be applied at keys only.
However, we then have to force a line break with %\n% between each key to ensure that the functionality reads it correctly:
{
"SkabelonDesign": {
"textualValue": "
<key1/><s><![CDATA[%\n%]]></s>
<key2/><s><![CDATA[%\n%]]></s>
<key3/><s><![CDATA[%\n%]]></s>
<key4/><s><![CDATA[%\n%]]></s>
<key5/>",
"bindingCollection": {
"key1": {
"SkabelonDesign": {
"type": "Text",
"binding": "CVPartner.project_experiences[0].long_description"
}},
"key2": {
"SkabelonDesign": {
"type": "Text",
"binding": "CVPartner.project_experiences[1].long_description"
}},
"key3": {
"SkabelonDesign": {
"type": "Text",
"binding": "CVPartner.project_experiences[2].long_description"
}},
"key4": {
"SkabelonDesign": {
"type": "Text",
"binding": "CVPartner.project_experiences[3].long_description"
}},
"key5": {
"SkabelonDesign": {
"type": "Text",
"binding": "CVPartner.project_experiences[4].long_description"
}
}
}
},
"lineBreakType": "Soft"
}
Excel [Back to top]
With DocumentData we can insert data into either cells or header/footer. Here's how:
Cells
To define a named range, select the cell(s) to be included, right click and select Define Name... option to present the dialog below.
The binding should then be added to the Comment field. The Name field is irrelevant for the purposes of document data however Scope needs to be set to Workbook.
Header/Footer
We can insert data in the header/footer of the sheet only from doc props. To do so, create a doc prop named one of the following depending on where in the sheet the data should be inserted:
HeaderLeftText HeaderCenterText HeaderRightText
FooterLeftText FooterCenterText FooterRightText
EvenPageHeaderLeftText EvenPageHeaderCenterText EvenPageHeaderRightText
EvenPageFooterLeftText EvenPageFooterCenterText EvenPageFooterRightText
FirstPageHeaderLeftText FirstPageHeaderCenterText FirstPageHeaderRightText
FirstPageFooterLeftText FirstPageFooterCenterText FirstPageFooterRightText
The value of this docprop should be a reference variable. In this example we will use <ModuleFooterText/>.
Now, we can create a second docprop with a reference to the DocumentData transformation. The second docprop should be named Binding_Root_Collection_0 (This will bypass the character limit of 255 in docprops by incrementing the number by 1). The value of the second docprop should be a json reference connecting the DocumentData transformation to the first docprop. In this example, the binding looks like this:
{"ModuleFooterText":{"SkabelonDesign":{"type":"Text","binding":"Module.FooterText"}}}
The variable Module.FooterText is defined in the module using DocumentData transform.
Example: header/footer
Below is an example of the above. Notice that the docprop values containing json- or xml values have been escaped. Notice also that all previous docprops called "Binding_Root_Collection" are removed prior to defining new ones.
<Cmd case="BaseExtensions:content-create" type="docprop" name="FooterLeftText" value="<ModuleFooterText/>"/>
<Cmd case="BaseExtensions:remove-doc-prop" prefix="Binding_Root_Collection" />
<Cmd case="BaseExtensions:content-create" type="docprop" name="Binding_Root_Collection_0" value="{"ModuleFooterText":{"SkabelonDesign":{"type":"Text","binding":"Module.FooterText"}}}"/>
<cmd case="SkabelonDesign.DocumentData:DefineData" variableName="Module.FooterText">
<IMan.Database>
<IMan.Database take="1"/>
<s><![CDATA[/]]></s>
<IMan.Number/>
<s><![CDATA[/v]]></s>
<IMan.Version/>
</IMan.Database>
<s/>
</cmd>
<Cmd case="SkabelonDesign.DocumentData:Commit"/>
It is also possible to format the headers and footers using VBA formatting. This should be done by inserting the formatting code in a <![CDATA[&L&12]]> element. Make sure that you use the alignment corresponding to the section the data is inserted in (i.e. left alignment in left section etc.).
It is important to note that there can only be added one formatting per header/footer section (left, center, or right). This is due to an Excel bug where mutliple formattings will show the inserted data as overlapping until the header/footer section is manually activated. See below image for example:
DateTime conversions
When binding date/time data to excel it is possible to ensure that it is displayed correctly in the output. The following binding ensures that values formatted as YYYY-MM-DDThh:mm:ss (ex. 2022-11-16T00:00:00+00:00) are outputted in a meaningful format. type should be defined as Date, ExpectedDataType should be defined as DateTime and format can be used to define the output format within excel.
{"SkabelonDesign":{"type":"Date","binding":"ApprovalDate","format":"dd-MM-yyyy", "ExpectedDataType":"DateTime"}}
Outlook [Back to top]
DocumentData can also both read and output to the different fields when composing a mail in Outlook. Contrary to Word, the variable names are predefined and there are no bindings. For example, when outputting to the subject line, when composing a mail, the variable name is Mail.Subject. See the example below from a client.
<cmd case="SkabelonDesign.DocumentData:DefineData" variableName="Mail.Subject">
<s>Vedrørende din sag – Medlem xxx</s>
</cmd>
You can insert the following values in variableName or elsewhere in DocumentData for reading and writing in mail fields.
Mail.To
This is for reading and writing in the recipient field of a mail.
Mail.Cc
This is for reading and writing in the Cc field of a mail.
Mail.Bcc
This is for reading and writing in the Cc field of a mail.
Mail.Subject
This is for reading and writing in the Cc field of a mail.
Mail.From
Note that you can only read from this field, as it is not a traditional editable field like the fields in a mail.
Comments
0 comments
Article is closed for comments.