Dynamics and Smart Templates Best Practices for Word

In order to enable Templafy Space owners on the extensive capabilities of the Dynamics module, we have accumulated a list of methods and techniques for building and maintaining data sources, forms, bindings and configurations for efficient and scalable smart templates!

Elements of a template that should be made dynamic

In our experience, there are elements of a template that should always be dynamic. Making these elements dynamic will ensure that your dynamic content is seamlessly updated in case of acquisition, integration or divestment of companies, scalable, consistent and on-brand. 

Elements of templates that should be made dynamic:

• Logo.
• Header.
• Footer.
• Sign offs (Regards, Best regards, Sincerely, etcetera).
• Disclaimer.
• User information and Office location.
• Document Classification (sensitivity labeling).
• Date fields.
• Repeated content.

Placeholder text best practices

When creating placeholders for smart fields (content controls), it is important that placeholders should be brief, descriptive (never an actual value), and unformatted. Placeholder texts like '[Date]', '[Subject]', and '[Disclaimer]' are preferred over placeholder text like [December DD, 20YY]', '[USE_ENTER_SUBJECT_HERE]', and '[DisclaimerTextForXYZCompany]'. 

Further, using the All caps setting in the font configuration for smart fields placeholder text can lead to unexpected consequences. It's recommended not to use it. The setting we are referring to is this one:

In some cases, using the 'All caps'-setting can lead to the dynamically inserted text to be completely capitalized after the Update document functionality was used (which was not the intention):

In other cases, using the 'All caps'-setting caused the dynamically inserted text to not work at all. 

Efficiently hide grouped elements

It is recommended to avoid using nested dynamic groups within templates whenever possible, because it may lead to unexpected behavior with the resulting values.

Below is an example of a nested and not nested group binding. The goal of the below bindings is to hide either Name1 and / or Name2 based on the end-user's answers to the response form questions:

The visibility expression for the first group binding on example 2 is:
{{IfElse(Equals(Form.Name, ""), VisibilityType.Hidden, IfElse(Equals(Form.Name2, ""), VisibilityType.Visible, VisibilityType.Hidden))}}

The visibility expression for the second group binding on example 2 is: {{IfElse(And(Equals(Form.Name, ""), Equals(Form.Name2, "")), VisibilityType.Hidden, IfElse(Equals(Form.Name2, ""), VisibilityType.Hidden, VisibilityType.Visible))}}

Make updating text that is shared between several templates a breeze (Group vs text element bindings)

In your template creation journey, you may find that there are blocks of text that are being used across several templates. These blocks of text may be inserted into the final document based on gating questions (dynamic forms). For these types of blocks of text or repeated content, it is best practice to create text elements from these blocks of text as opposed to keeping the blocks of text in each template and controlled with a Group binding and visibility expression. This way, if anything changes to the block of text, it just needs to be updated in one location and the change will update in every template it is used!

Seamlessly manage the visibility of text elements within smart templates

When attempting to hide a text element within a smart template, it is best practice to use the visibility setting within the template (the text element content control) rather than using the visibility setting within the text element itself. Below is the example 'Retirement Plan'.

Recommended, no visibility setting around the entire text of the text element:

Not recommended, visibility setting around the entire text of the text element:

To use the visibility within the template instead of within the text element, create a checkbox form called 'Show_Retirement_Plan' to select whether the text element should be shown:

In the past, in order to set the visibility of this text element, the text element binding would have been wrapped in a Group binding that had visibility settings (like the below screenshot). This is no longer best practice!

The current best practice is to create the text element binding with a custom visibility setting. In this example that will hide the text element if the checkbox remains unchecked during document creation:

Visibility expression for reference: {{IfElse(Form.Show_Retirement_Plan, VisibilityType.Visible, VisibilityType.Hidden)}}.

Applying group visibility within text element best practices

As described before it is not recommended to use a group visibility setting around the entire text of the text element. When you use group visibility on specific parts of a text element, take care of the following:

• The last paragraph of a text element should not contain a group. If the last paragraph contains a group then in some situations this can cause unexpected behavior.
  For example if a template contains multiple text elements below each other and the text elements contains a heading, the heading might not be shown correctly when the document is created. To avoid this behavior, add an extra paragraph after the paragraph containing the group. Make the extra paragraph e.g. font size '1' so the output will not show a visible empty line.
• In general we recommend to use VisibilityType.Hidden for a group when a document has the option 'Update document' enabled. Only when the text element (or document) contains a numbered list which has groups that can be shown or hidden, use VisibilityType.Delete for these groups to get this list properly numbered.
• When a text element contains a table which rows can be shown or hidden, and the document needs to be updated, use VisibilityType.Hidden for these grouped rows.

Comprehensive testing procedures

It is important to thoroughly test newly created or recently updated smart templates before making them live to the end users. 

Below is a list of items/acceptance criteria to keep in mind when testing your smart templates:

• Use a test tenant or Space to perform your testing:
  • If you do not have a test tenant or Space, please contact your Templafy Account Manager for more details.
  • If no test tenant or Space is available, create the template or copy the existing template into a filtered folder while testing is taking place. More information on how to filter folders can be found here. 
• Test all of the different combinations of (gating) questions, both new and old, to ensure that all scenarios are accounted for. This includes all dropdowns, flexible dropdowns, checkboxes, etcetera. 
• Test templates also with the Update document functionality (if applicable).

Maintaining smart templates

Once a smart template has been created using the aforementioned best practices, maintenance of that smart template becomes paramount. 

One of the most important things to remember when updating either a template or text element in the Templafy library, is to download the template or text element first from the Templafy library, update it, and then use the replace functionality to upload it back into the Templafy library. Using the replace functionality will ensure that the original Asset ID is retained and will not break any content using the template or text elements.

Build easily identifiable reference fields within data sources

When building data source schemas and adding fields that refer to other data sources, use a naming convention, e.g. 'Data source name+Ref'. This way, referenced fields are easily identifiable when using them as drop downs in Dynamic content. For example, if the Offices data source is referring to the data sources Regions, Countries and Cities, the fields that will be created in the Offices data source should be named RegionsRef, CountriesRef and CitiesRef as seen below:

Or you can keep the field names short and clear, like Region, Country and City: