Working with the Template Designer

About the Template Designer

1. What is the Template Designer

2. Pre-requisites for using Template Designer

3. Opening Template Designer

4. Enabling dynamics and DCU

5. About Content Controls & Shapes

 

Working with the Template Designer

6.1 Configure and insert bindings

• 6.1.1 Date
• 6.1.2 Group (Word only)
• 6.1.3 Image 
• 6.1.4 Text (Word only)
• 6.1.5 Text element (Word only)
• 6.1.6 Replace on update

 

6.2 General settings for bindings

• 6.2.1 Remove and keep content
• 6.2.2 Disable updates

 

6.3 Configure Document

• 6.3.1 Color theme
• 6.3.2 Custom Document Property 
• 6.3.3 Custom XML
• 6.3.4 Document properties
• 6.3.5 Image header (Word only)
• 6.3.6 Page setup (Word only)
• 6.3.7 Proofing language

 

6.4 Advanced template configuration (JSON)

 

6.5 Review Content Control settings

 

1. What is the Template Designer?

The Template Designer is a Graphical User Interface (GUI) based tool available in the VSTO add-in. The Template Designer is used for configuring dynamic templates. 

 

There are three main tabs in the Template Designer: 

• Elements: insert bindings.
• Document: configure document.
• Settings: Advanced template configuration such as enabling document updater (DCU), working with JSON (JavaScript Object Notation)

 

 

 

2. Pre-requisites for using the Template Designer

• Templafy Dynamics module.
• Templafy Office Add-ins version 5.4.2.xxx or higher.
• User needs to have SuperAdmin rights on the Templafy solution.
• The "Transformation pipeline" feature must be enabled. Contact your implementation partner if this does not appear to be enabled, and you believe that it should be.
• Office 2013 or later.

 

3. Opening the Template Designer

To open the Template Designer, a Microsoft Office program must be open, e.g. Word. When this is open, the Templafy Task Pane will appear on the right side of the screen. Select the three dots in the top right corner of the Templafy Task Pane. These will bring up a drop-down list, and the ‘Template designer’ option should be selected.

 

Word		PowerPoint

 

4. Enabling dynamics and Document Content Updater

Before getting started on the actual configuration of the template, there are a couple of necessary steps needed to enable the template for dynamics.

 

1. Click the 'Settings' tab in the Template Designer section of the Templafy Task Pane. 

 

2. Click the button "Enable Document Content Updater"

 

3. Dynamics are now enabled for the document.

 

5. About Content controls & Shapes

 

Word

In Word, Templafy uses Content Controls to insert bindings. Templafy stores the binding as a JSON code string in the tags field located in Content Control Properties.

To view the properties, click on the content control. In the Word ribbon, choose the 'Developer' tab, select 'Controls', and then click on 'Properties.

 

 

Note: By default, the Developer tab is not enabled on the Office Ribbon. Information about how to enable it can be found here.

 

Content control properties:

 

Example of content controls in a letterhead:

 

 

Powerpoint

In PowerPoint, Templafy uses Shapes to insert bindings. Templafy stores the binding as a JSON code string in the Alt Text field in a Shape. To view the Alt Text, right click on the shape, then select 'Edit Alt Text'.

 

Alt Text field for a shape:

 

Example of a shape used when inserting a logo:

 

6.1 Configure and insert bindings

How to configure a binding:

1. Place the cursor in the relevant place in the document or presentation. 
2. Choose which type of placeholder you need. 
3. Choose the binding (this is the logic that determines which data to insert).
4. Click 'Create'.  

2. Choose the binding type from these options:

• Date
• Group
• Image
• Text
• TextElement (requires Dynamics version 1.1)

Depending on your choice, different configuration options will be shown.

Choose 'binding' from the drop-down. The binding contains the business logic that determines what data will be inserted when the document is created. 

Note:

• If no bindings are shown, or you are missing bindings you need, make sure you have the relevant datasources and fields in the user profile and forms.
• In the Template Design, you are only presented with the last dropdown in a list of dropdowns pointing to the same datasource, when you search for the binding name in the template designer (as shown below). The functionality is still there, so you can still type the binding name knowing what datasource and which row to refer to. But it's a limitation by design to not show everything in there, simply to avoid a very long list of suggestions. 

 

A 'binding' is a tag string that refers to where the choice has been made by the end-user.

For more about tag strings read here.

 

6.1.1 Configuring date

1. Choose date in the first dropdown on the Elements tab
2. Specify the binding that determines what format the date should be inserted. In the example below {{DateFormats.<ValueFromTypeColumn>}} where the <value> is the type column from the dateformats datasource, eg. {{DateFormats.CustomA}}
3. Choose the binding from the dropdown where the date input is made by the user. In the example below it is a Form Field named Date.

NOTE: Setting up dynamic dates needs both language and dateformat input specified in mandatory data sources. For more information - please click here.

 

 

 

6.1.2 Group visibility settings (show / hide)

Group configuration is used to either hide or delete other bindings/elements/pictures depending on the choices made by the end-user. You can read more here.

Grouping elements make it possible rearrange text and elements in a document based upon choices made by a user.

 

6.1.3 Image

Width/Height: These fields can either be static by simply typing xx cm (ex 2.2 cm) or you can make it static using an expression binding which is linked to a data source. All fields which contain {{}} are applicable for expression bindings. The structure of an expression binding will look at the following {{Form.Datasource.ColumnName}}

 

6.1.4 Text

 

More information about working with bindings can be found in the top of the document or by clicking here

 

6.1.5 TextElement

Required Dynamics version for the textElement feature is 1.1. 

It is possible to insert a specific text element into a content control or specify an expression binding to the text element inserted is based on user choices in a form or user profile.

 

You can read more about uploading text elements to the text library here

You can read more about Inserting Text Elements into Content controls here. This document give an in depth look into how to combine forms and datasources in relation to working dynamically with text elements.

 

6.1.6 Replace on update

Checking this box: will keep the content control in the document so this can be used when using the Update Document feature. Everything inserted originally in the content control will be replaced when using DCU feature.

The content control will remain locked when "replace on update" is checked.

Leave unchecked: will keep the content control in the document, but text inserted at document creation will remain despite DCU being activated - but - any bindings within the original text element will be update.

 

6.2 General settings for bindings

These settings you'll find on several places in the Template Designer. The functions and how to set it up are the same.

 

6.2.1 Remove and keep content

Checking this box will "keep the text inserted" and remove the content control. The text is editable by users and since the content control is removed, DCU does not apply.

 

6.2.2 Disable updates

Check this box if you don't want the value inserted in the content control to be updated using DCU.

The content control is kept and locked for editing

 

 

6.3 Configure document

In the Document tab, there is a list of options that can be setup on a document level:

 

6.3.1 Color theme

1. Open Template Designer
2. Click "Document tab"
3. Choose color theme from the dropdown
4. Specify a binding that links user choice to an actual color theme

Pre-requisites

• VSTO-add-in version 5.5.1.1312 or greater
• Transformation version 1.3
• Color theme uploaded to Templafy
• Column in a data source if color theme should be applied based on user input

For more on this - please click here

To find out which version of Templafy Desktop you are running - please click here

 

A generic example of binding

{{Userprofile.FieldName.ColumnName}}

FieldName is the name of the field in the Userprofile

ColumnName is the name of the column in the datasource where the color theme is specified.

 

Specific example

If colortheme is based on Legalentity choice in the user profile it will typically look like this 

{{Userprofile.Legalentity.colortheme}}

given that the column in the Office datasource is named colortheme

 

 

Default Color Theme

If the Admin wishes to have just a color theme being added by default to the document upon creation, no binding is needed. The admin just needs to upload the color theme xml file to Templafy, and then reference the name of that file (without curly brackets) in the colorTheme field of document properties.

You can read more about how to upload and apply a color theme here

 

6.3.2 Custom Document Property 

Click the "+" sign to get to the binding configuration menu 

 

 You can read more about properties here

 

6.3.3 Custom XML

With CustomXML can you store document data in 3rd party systems such as e.g. SharePoint. This can be data such as metadata of the document. This CustomXML feature can be accessed in Template Designer --> Document. This feature can be used in Word, PowerPoint, and Excel. A prerequisite for using CustomXML is a Dynamics Version which is 1.5 or higher. 

The CustomXML can be either static or dynamic. 

Examples of CustomXML:

• Static

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

• CustomXML with one binding

<?xml version="1.0" encoding="utf-8"?><CustomElement>{{UserProfile.LegalEntity.Office}}</CustomElement>

• CustomXML with multiple bindings

<?xml version="1.0" encoding="utf-8"?>
<CustomElement>
  <LegalEntityOffice>{{UserProfile.LegalEntity.Office}}</LegalEntityOffice>
  <LegalEntityName>{{UserProfile.LegalEntity.Name}}</LegalEntityName>
  <Name>{{UserProfile.Name}}</Name>
  <Date>{{Form.Date}}</Date>
</CustomElement>

 

 

6.3.4 Document properties

 

 

You can read more about properties here

 

6.3.5 Image header (Word only)

 

 

Binding: Refers to the image which you want  to insert. We use the traditional way of binding which is UserProfile.FormName.ColumInDataSource. If the image was referred from the Datasource office the binding and the columname was called OfficeLogo, then the specific binding would look the following UserProfile.Office.OfficeLogo.

 

ShapeName: Is the specific naming of the ImageHeader which you are working on. If you give call the ShapeName "ExampleImageHeader" it will look like the following: 

 

 

Width/Height: These fields can either static (you can write ex. 2.9 cm) or you can make this dynamic via the ex. the Office datasource. If you put in specific dimensions in your Office datasource you can make an expression binding and referee to this binding and hereby make the document dynamic. If you ex. call the columnname in the Office Datasource "LogoHeight" then the specific binding would look like this {{UserProfile.Office.LogoHeight}}

NamedSections: Can you chose if you want the image related to specific sections (section breaks) in the document. 

NamedPages: On which page do you want the header. If the default is chosen the image will appear from page 2 and onwards. You have the possibility to make the image be visibility on the first page, even pages, off pages, all pages or start from the second page

LeftOffset: You have the possibility to insert the picture x amount of centimeters from the left. You can choose to make this binding either static or dynamic (as shown with width/height).

TopOffset: You have the possibility to insert the picture x amount of centimeters from the top. You can choose to make this binding either static or dynamic (as shown with width/height).

ImageTextWrapping: You can choose to have the image either inFrontofText and behindText. 

Rotation: You can rotate the picture either 90 degree clockwise, 180 degree clockwise or 90 degrees counter clockwise. 

 

6.3.6 Page setup (Word only)

You can read more about setting up a custom word document here

You can read more about applying a color theme here

 

6.3.7 Proofing language

Click the "+" sign to get to the binding configuration menu:

 

 

When choosing a {{Binding}} for language you can either choose to directly type an Iana code (ex. da-DK for Danish) which will make the document static bound to only be in a specific language or you can choose to make an expression binding which is linked to a Userprofile and make the proofingLanguage dynamic. To bind to document language to an Userprofile you will need to type {{DocumentLanguage}} in the above shown language box.

 

Settings tab (Advanced template configuration, JSON)

To access the JSON code from the template and the attached forms then go to "Settings" and hereafter click "Advanced Configuration"

 

 

Now you can check the "Template" and "Form" JSON code:

 

 

The above shown picture is a snippet from a newly create document in version 1.3 with Document Content Updater enabled:

 

{
 "elementsMetadata": [],
 "transformationConfigurations": [],
 "enableDocumentContentUpdater": true,
 "version": "1.3"
}

 

From the Controls section in Word, select the desired content control type. Word 2016 supports content controls like Rich Text, Plain Text, Picture, Building Blocks, Drop-Down Lists, Checkboxes and more.

In this step by step process, we will add Rich Text Content Control. 

 

 

Review Content Control settings

Content Control settings and properties can be revisited with Templafy Template Designer, or with the Content Control Properties dialogue in Word.

In Template Designer

Select the content control that you would like to add functionality to.

Open Template Designer. The content control properties are visible in the Settings section when the content control is selected in the Word document.  

It is possible to specify conditions to which the content control should respond in the Visibility Section. Content Controls can be either hidden or deleted if the binding is empty. 

 

In Word