Template Assistant

Operating System: Windows

empower® Add-in: Docs
Label_For_Administrators.svg

For empower® Administrators, the option Template Assistant is accessible via the split button Fill in document in Word.

To open the Template Assistant in the side pane, click on the lower part of the split button Fill in document (Figure 1, “Button Fill in document”).

Figure 1. Button Fill in document

Button Fill in document

Then, choose the option Template Assistant (Figure 2, “Option Template Assistant”).

Figure 2. Option Template Assistant

Option Template Assistant

It allows you to create placeholders that can be filled in with data from the EAV (Entity-Attribute-Value) model.

This is done using an .xml structure that accesses data from the EAV model. The placeholders are filled in with profile, company and location data when a user uses the Document Template.

The EAV Editor is a separate tool which allows to configure the user interface for data input.

This includes the data entry fields, their translations, and additional data fields for technical information.

To understand how to work with the EAV Editor and EAV model, the following terms need to be defined:

  • Property – Complete data field with a label, originating from the EAV Editor, and a value input field in the company or profile management.

  • Value – Content entered into the input fields in the user interface which is used to fill in templates.

  • Label – Display name for a property in the user interface or in filled-in templates.

  • Entity – Collection of properties for a single data group.

To display data within a document, the Template Assistant uses Rich Text Content Controls. These serve as placeholders for the content.

The Template Assistant opens in the side pane and is divided into three sections:

  • Custom XML Editor – Enables users to edit the user-specific .xml section and to test the configuration directly in Word.

    Usually, this section has an informational character and is not manually changed.

  • Document Metadata – Enables users to edit the user-specific .xml section. The Template Assistant supports the user entering the syntax.

  • Document Variables – Displays all document data, e.g. last modification date, editor and placeholder sizes.

    Usually, this section has an informational character and is not manually changed.

Use the Template Assistant

With the help of the Template Assistant, you can add text and picture placeholders to the template.

You can use the Template Assistant to add a logo placeholder or to add data placeholders that will be filled in with profile and company data.

Add Text to a Template

To add data placeholders to a template using the Template Assistant, follow the following steps:

  1. In the empower® Ribbon, click on the lower part of the split button Fill in document.

  2. Choose the option Template Assistant.

    The Template Assistant opens in the side pane on the right-hand side of your Word window. It opens in the section Document Metadata.

  1. Under Content Controls, click on the plus sign next to Filter (Figure 3, “Add Rich Text Content Control” (1)).

    A drop-down menu opens.

  2. Choose the option Rich Text Content Control (Figure 3, “Add Rich Text Content Control” (2)).

    A rich text content control is inserted at your current cursor position.

Figure 3. Add Rich Text Content Control

Add Rich Text Content Control

  1. Under Document Properties, click on the button Set to current database ID (Figure 4, “Button Set to current database ID”).

    The database ID cannot be set individually.

Figure 4. Button Set to current database ID

Button Set to current database ID

  1. Under Content Controls, you can see the content control you have just added to your document.

    Enter a unique name for this content control in the input field Title (Figure 5, “Rich Text Content Control Fields” (1)).

  2. To assign a valid GUID to the content control, click on the button GUID next to the input field Tag (Figure 5, “Rich Text Content Control Fields” (2)).

    An automatically generated and unique ID is assigned to the content control.

  3. Assign the required group to the content control (Figure 5, “Rich Text Content Control Fields” (3)).

    For further information, see Placeholder Groups.

  4. If you want to enable users to hide the content control for printing processes, tick the checkbox for Stationery (Figure 5, “Rich Text Content Control Fields” (4)).

Figure 5. Rich Text Content Control Fields

Rich Text Content Control Fields

  1. The input field Syntax provides access to the EAV model structure.

    To add the required placeholders, follow the following steps:

    1. Click on the plus symbol next to the input field (Figure 6, “Insert Syntax Elements”).

      A drop-down menu opens.

    2. Choose an entity to expand the properties.

    3. Choose the required property.

    4. Then, define if you want to add the value or the label to the placeholder.

      The placeholder will now be filled in with the corresponding syntax.

Figure 6. Insert Syntax Elements

Insert Syntax Elements

  1. To save the values, click on the button Save Document Metadata (Figure 7, “Button Save Document Metadata”).

Figure 7. Button Save Document Metadata

Button Save Document Metadata

Important

The Template Assistant provides a quick access to the basic EAV model categories via the drop-down menu. All entities that have been added manually to the EAV model need to be entered manually.

Additional entries are usually added by empower during your onboarding process.

For further information regarding the manual composition of variables, see Compose Variables Manually.

Note

In the drop-down menu, you can hover over the label or value to display a preview for your current default profile and company or location.

It shows the values which would be displayed in the document for the current profile (Figure 8, “Mouse-Over for Values”).

Figure 8. Mouse-Over for Values

Mouse-Over for Values

Note

If you choose to hide the content control when printing, the content control and its content might still be visible if you are currently displaying the formatting symbols.

However, it will not be included in the printed version.

You can also add custom text blocks to your template.

These can be used for recurring text such as greeting and farewell formulas. These texts stay the same regardless of the subject or addressee of the document or signature.

Custom text blocks are created in the EAV Editor and can then be added to a template using a content control.

The pattern for custom text blocks is as follows:

{{TextBlocks.[PROPERTY NAME].Value}}

In addition, you can create custom placeholders via the EAV Editor and then use them in your template.

These can be used to simplify using multiple fields in one placeholder.

Custom placeholders themselves can be reused inside of other custom placeholders. There is a maximum of 50 levels for this recursion.

The pattern for custom placeholders is as follows:

{{CustomPlaceholders.[PROPERTY NAME].Value}}

The following is an example for the use of custom placeholders:

Example

The following placeholder is shortened using a custom placeholder:

{{User.First_Name.Value}} {{User.Last_Name.Value}}

The custom placeholder would be the following:

{{CustomPlaceholders.UserDisplayName.Value}}

This placeholder contains both the value for the first name and the value for the last name.

The outcome for a user called empower Admin would be the following:

Word_TA_Example_Custom_Placeholder.png

Placeholder Groups

In the Template Assistant, you can assign each content control to a group.

The placeholder groups are necessary for the workflows to work in the correct order.

There are two available groups (Figure 9, “Placeholder Groups Drop-Down Menu”):

  • Empty – Used for profile, company and location data

  • Recipient Address – Used for Outlook data of a chosen Outlook contact

Figure 9. Placeholder Groups Drop-Down Menu

Placeholder Groups Drop-Down Menu

The placeholder groups are used to distinguish the two types of placeholders.

Content controls which are assigned to the empty placeholder group are filled in with profile, company and location data for the current user.

Content controls which are assigned to the placeholder group RecipientAddress can be filled in with data for a choosable Outlook contact.

Therefore, the profile, company and location data for the current user is filled in first. Then, the template is filled in with the missing data from Outlook.

Important

If the content controls are assigned to the placeholder group Recipient Address by mistake, they might be filled in with the wrong profile or contact data.

Note

If there is no content control for the recipient address, the user will be asked if they want to insert the data at their current mouse cursor position (Figure 10, “Dialog Box No Placeholder Found”).

Figure 10. Dialog Box No Placeholder Found

Dialog Box No Placeholder Found

For further information regarding the user perspective for the recipient address, see Add the Recipient Address.

Compose Variables Manually

In the syntax in the Template Assistant, variables are used to reflect the EAV data scheme that is managed in the EAV Editor.

These variables can be composed manually.

To do so, follow the following steps:

  1. Place the variable inside double curved brackets (Figure 1, “Curved Brackets”).

Figure 1. Curved Brackets

Curved Brackets

  1. Inside these brackets, first enter the entity (Figure 2, “Example for Entity”).

    1. To do so, navigate to the entity and its property in the EAV Editor you want to use.

    2. Then, enter the respective entity's name.

  2. Add a full stop after the entity.

Figure 2. Example for Entity

Example for Entity

  1. Now, enter the property right afterwards (Figure 3, “Example for Property”).

    1. To do so, navigate to the property inside the entered entity.

    2. Then, enter the respective property's name.

      Make sure you use the exact same spelling as in the EAV Editor.

  2. Add a full stop after the property.

Figure 3. Example for Property

Example for Property

  1. Then, either enter Label or Value, depending on what part of the property you want to display.

    Enter Label to display the title of the field (Figure 4, “Label”).

    Enter Value to display the content of the field (Figure 5, “Value”).

  2. Check if your variable contains all required parts.

Figure 4. Label

Label

Figure 5. Value

Value

The following is an example for the use of variables:

Example

A variable is composed to result in the following text:

Website: empowersuite.com

For this text, the following variable can be used:

{{Location.Website.Label}}: {{Location.Website.Value}}

Location is the entity name.

Website is the property name.

Note

For the basic EAV model, you do not need to compose the variables manually. Here, you can use the plus symbol next to the field Syntax in the Template Assistant to access the EAV data scheme and add new variables.

For further information, see Use the Template Assistant.

Advanced Formatting and Syntax

The basic functionalities of the Template Assistant provide you with a rather static template.

To make the syntax more variable, you can use if conditions and formatting tags.
Apply Text Styles

You can also assign text styles to Rich Text Content Controls to always format them accordingly.

To do so, follow the following steps:

  1. Select the Rich Text Content Control.

  2. In the tab Developer, click on the button Properties (Figure 6, “Button Properties”).

Figure 6. Button Properties

Button Properties

  1. Tick the checkbox for Use a style to format text typed into the empty control (Figure 7, “Text Style Options”).

  2. Then, select the text style you want to apply.

    Alternatively, create a new text style from scratch by clicking on the button New Style….

Figure 7. Text Style Options

Text Style Options

Important

It is not possible to use different font sizes, text styles or font colors to format content within one Rich Text Content Control. All contents within the Rich Text Content Control have to be formatted with one style only.

For further information on how to manipulate the formatting of single contents within one Rich Text Content Control, see Add Formatting Tags.

Note

For further information regarding the tab Developer and how to make it available, see Show the Developer tab.

Add Formatting Tags

The following table provides an overview of formatting tags that can be used to adjust the document output via the Template Assistant:

Format

Tag

Example

Line Break

[n/]

Text[n/]Text

Bold

[b] … [/b]

[b]Text[/b]

Underlined

[u] … [/u]

[u]Text[/u]

Italics

[i] … [/i]

[i]Text[/i]

Tab Stop

[t/]

Centered

[hcenter] … [/hcenter]

[hcenter] Text Text [/hcenter]

Align Right

[hend] … [/hend]

[hend] Text Text [/hend]

Justified

[hdistribute] … [/hend]

[hdistribute] Text Text [/hdistribute]

Uppercase

| Upcase

{{Text | Upcase }}

Hyperlink

[a target="linkTargetUri"] … [/a]

For normal hyperlinks:

[a target="https://{{Entity.Property.Value}}";] {{Entity.Property.Label}}[/a]

For e-mails:

[a target="mailto:{{Entity.Property.Value}}"]{{Entity.Property.Value}}[/a]

The following is an example for a use case of formatting tags:

Example

The labels in the following code excerpt are written in uppercase letters and displayed in bold.

The values, on the other hand, are written in standard formatting without uppercase letters.

Additionally, the data set is divided into three lines using line breaks.

The following excerpt shows the configuration for this example:

{{User.First_Name.Value}} {{User.Last_Name.Value}}[n/][b]{{User.Phone.Label | Upcase }}:[/b] {{User.Phone.Value}}[n/][b]{{User.Email.Label | Upcase }}:[/b] {{User.Email.Value}}

The outcome for a user called empower Admin would be the following:

Word_TA_Example_Formatting_Tags.png
Apply If Conditions

If conditions can be used to make the display of values more flexible.

For example, you can define that the label for mobile_phone is only shown if a mobile phone number is entered in the profile.

If conditions always consist of an opening and a closing tag, each enclosed in a pair of curly brackets.

The pattern is as follows:

{% if [CONDITION] %} … {% endif %}

The following table provides an overview of possible comparison operators:

Type

Operator

Equal

==

Not Equal

!=

Greater Than

>

Less Than

<

Greater Than or Equal to

>=

Less Than or Equal to

<=

Note

In addition, you can use the operators AND and OR.

The following is an example for a use case of if conditions:

Example

If no value is entered for a property in the selected profile, you can use an if condition to ensure that the property is not displayed in the document either.

The following excerpt shows an example of such an if condition, where the label for mobile_phone is not displayed if no mobile phone number is entered in the profile:

{% if User.Mobile_Phone.Value != null %}{{User.Mobile_Phone.Label}}: {{User.Mobile_Phone.Value}}{% endif %}
Apply Else If Conditions

Else if conditions can be used within if conditions. If the if condition does not apply, the else if condition within the if block is evaluated.

There is no limitation on the number of else if conditions that can be included.

The pattern for an else if condition is as follows:

{% if [CONDITION] %} … {% elseif %} … {% endif %}

The following is an example for a use case of if conditions:

Example

If the primary option is not available or not entered, an alternative is selected. If neither of the two values is available, the label is omitted.

The following excerpt shows the else if condition for this example:

{% if User.Mobile_Phone.Value != null %}{{User.Mobile_Phone.Label}}: {{User.Mobile_Phone.Value}}{% elseif User.Phone.Value != null %}{{User.Phone.Label}}: {{User.Phone.Value}}{% else %}{% endif %}

In this example, the else branch has been left empty. If a value is specified here, that value will be used.
Apply For Loops

For lists that contain multiple entries of the same type (e. g., Managing Directors), for loops can be used. For loops consist of an opening and a closing tag enclosed in a pair of curly brackets.

Within the for loop, enter a variable that represents the values from your list. This variable is placed between two pairs of curly brackets.

The pattern for such a for loop is as follows:

{% for [VAR] in [ENTITY VARIABLE] %}{{VAR}}{% endfor %}

Typically, for loops are used for the properties of the type Array, which usually display the following company information:

  • Managing Directors

  • Board of Managers

  • Banking Information (if more than one bank is added to the company)

The following is an example for the use of such for loops:

Example

A list of entries for Managing Directors is created. It is introduced by a label and is separated by line breaks.

The following excerpt shows the configuration for this example:

{{Company.Managing_Directors.Label}}:[n/]{% for MD in Company.Managing_Directors.Value %}{{MD}}[n/]{% endfor %}

The outcome for a company whose managing directory are empower Admin and empower User would be the following:

Word_TA_Example_For_Loop_Managers.png

If the entries in the list consist of multiple properties per value, first enter the variable followed by a period. Then specify the property and the type (label or value):

{% for [VAR] in [ENTITY VARIABLE] -%} {{VAR.PROPERTY.Label}}: {{VAR.PROPERTY.Value}}, {% endfor %}

The following is an example for the use of such for loops:

Example

A list of entries for bank information is to be created, where each entry consists of three properties.

The following excerpt shows the configuration for this example:

{% for BI in Company.Banking_Information.Value %}{{BI.Name.Value}}: {{BI.IBAN.Label}}: {{BI.IBAN.Value}}, {{BI.BIC.Label}}: {{BI.BIC.Value}}{% endfor %}

The outcome for a company's banking information could be the following:

Word_TA_Example_For_Loop_Bank.png

List entries can be separated by line breaks, delimiters, commas, etc.

You can use formatting tags to change the formatting of each property.

For example, the name of a bank can be displayed in bold, while the rest of the entries remain unformatted.

Use an unless tag to apply an alternative formatting, for example, when the last list entry is being processed.

The pattern for this configuration is as follows:

{% for [VAR] in %}{{VAR}}{% unless %} ... {% endunless %}{% endfor %}

The following is an example for the use of such for loops:

Example

A comma should be inserted after each list entry to separate the entries from one another.

A comma should not be inserted after the last entry in the list.

The following excerpt shows the configuration for this example:

{{Company.Managing_Directors.Label}}: {% for MD in Company.Managing_Directors.Value -%}{{MD}}{% unless forloop.last %},{% endunless %}{% endfor %}

The outcome for a company whose managing directory are empower Admin and empower User would be the following:

Word_TA_Example_For_Loop_MD_List.png
Apply Filters

Filters are special functions used to adjust and format data from templates.

Filters are implemented as follows:

{{ [VARIABLE NAME] | [FILTER NAME]: Argument }}

The following table provides an overview of filters that are usually used with empower®:

Name

Function

Syntax

Capitalize

The first character in a string is capitalized.

{{ [PROPERTY NAME] | Capitalize }}

Upcase

All characters in a string are written in uppercase.

{{ [PROPERTY NAME] | Upcase }}

Downcase

All characters in a string are written in lowercase.

{{ [PROPERTY NAME] | Downcase }}

Replace

Substrings are replaced by another substring.

{{ [PROPERTY NAME] | Replace: "cats", "dogs" }}

Size

Defines the number of characters in a string or array.

{{ [PROPERTY NAME] | Size }}

Strip

Whitespaces prior to or after a string are removed.

{{ [PROPERTY NAME] | Strip }}

In front of the pipe symbol, enter the property name and type (label or value) of the property you want to filter.

You can use multiple filters at once if you separate them with a pipe symbol.

The pattern for such a filter is as follows:

{{ [VARIABLE NAME] | Filter1 | Filter2 }}

The following are examples for the use of filters:

Example

A filter is to be applied to ensure that the characters $% are used as a line break.

This filter can be used, for example, when a string contains multiple values that should be split across multiple lines.

The following excerpt shows the configuration for this example:

{{Location.Address.Value.Street.Value | Replace: "\$\%", "[n/]"}}

The string for Street in the company management window would look as follows:

Word_TA_Example_Replace_Filter_Company_Management.png

The outcome in the template would be the following:

Word_TA_Example_Replace_Filter_Outcome.png

Example

You want to create a custom variable that adds the number of characters of two values and determines whether they fit into a single cell or need to be separated by line breaks.

The following excerpt shows the configuration for this example:

{% assign charLength = Location.Website.Value.size | Plus: Location.Email.Value.size %}{{Location.Website.Value}}{% if charLength >46 %}[n/]{% else %}, {% endif %}{{Location.Email.Value}}

The outcome for a combination with less than or equal to 46 characters would be the following:

Word_TA_Example_Filter_Character_Limit_Match.png

The outcome for a combination with more than 46 characters would be the following:

Word_TA_Example_Filter_Character_Limit_No_Match.png

Note

Filters can be used with regular expressions. Therefore, make sure to escape special characters correctly.

Add Logos to a Template

To add a logo placeholder to a template using the Template Assistant, follow the following steps:

  1. In the empower® Ribbon, click on the lower part of the split button Fill in document.

  2. Choose the option Template Assistant.

    The Template Assistant opens in the side pane on the right-hand side of your Word window. It opens in the section Document Metadata.

  1. Under Content Controls, click on the plus symbol next to Filter (Figure 8, “Add Picture Content Control” (1)).

    A context menu opens.

  2. Choose the option Picture Content Control (Figure 8, “Add Picture Content Control” (2)).

    A picture content control is inserted at your current cursor position.

  3. Adjust the size of the content control via the option Size and Position… in the content control's context menu.

    1. Ensure that the checkbox Lock aspect ratio is not ticked.

    2. Format the content control with In line with text.

Figure 8. Add Picture Content Control

Add Picture Content Control

  1. Click on the button Load Document Metadata (Figure 9, “Button Load Document Metadata”).

Figure 9. Button Load Document Metadata

Button Load Document Metadata

  1. Under Content Controls, you can see the content control you have just added to your document.

    Enter a unique title for this content control in the input field Title (Figure 10, “Picture Content Control Fields” (1)).

  2. To assign a valid GUID to the content control, click on the button GUID next to the input field Tag (Figure 10, “Picture Content Control Fields” (2)).

    An automatically generated and unique ID is assigned to the content control.

  3. Assign the required group to the content control (Figure 10, “Picture Content Control Fields” (3)).

    For further information, see Placeholder Groups.

  4. If you want to enable users to hide the content control for printing processes, tick the checkbox for Stationery (Figure 10, “Picture Content Control Fields” (4)).

    This usually makes sense if you work with pre-printed paper.

Figure 10. Picture Content Control Fields

Picture Content Control Fields

  1. To save the values, click on the button Save Document Metadata.

The logo placeholder will automatically be filled in with the correct logo according to your company and location data.

Therefore, make sure to add logos to your company and location data.

For further information regarding the company and location management, see Company Management.

The logo will never be displayed distorted. It will be displayed as large as possible in the placeholder.

Note

For further information regarding the logo selection, see Company Management.

For further information regarding the work with logos, see Work with Logos in Templates.

Note

If you choose the hide the content control when printing, the content control and its content might still be visible if you are currently displaying the formatting symbols.

However, it will not be included in the printed version.

Was this article helpful?

/

Comments

0 comments

Article is closed for comments.