<h1>Document templates</h1>
<p>Document templates allow users to create new contract documents based on predefined documents. The objective is to apply as much information from the contract's metadata as possible. For this purpose, the templates can contain <span
style='font-weight:bold;font-style:italic'>placeholders</span> which are replaced with data from the contract when the <a
href="#!/guide/p987E8B3B_D687_486E_A601_F4A3D4ED84EA">document is created</a>.</p>
<h2>Edit document templates</h2>
<p><span class="tag_warning">Document templates must be <code>.doc</code> or <code>.docx</code> Microsoft Word documents, otherwise placeholders cannot be replaced. Furthermore, they have to be filed using the <span
style='font-style:italic'>Contract document</span> keywording form.</span></p>
<h3>Change document templates via the configuration</h3>
<p>You can edit templates via the contract management configuration right in <span
style='font-weight:bold;font-style:italic'>Document templates</span>. You can add new templates, or edit or delete existing ones.</p>
<p>{@img img1.png}</p>
<h3>Change document templates via the repository tree</h3>
<p>Document templates are filed to the <code>Administration\Business Solutions Custom\contract\Configuration\Document Templates</code> folder. It is also possible to structure them further by using folders.</p>
<p>{@img img3.png}</p>
<h2>CUSTOM fields</h2>
<p>A list of custom fields can be added for each document template that are called up when creating the contract. CUSTOM fields can then be replaced with placeholders in Word.</p>
<blockquote>
<p><span
style='font-style:italic'>A new framework contract is concluded for sales. For this document type, the product name, purchase quantity, and maximum number of partners are required in the Word document in addition to the general contract data. This information can be called up directly via CUSTOM fields when creating the document and set automatically.</span></p>
</blockquote>
<p>The following figure shows how custom fields are used when creating a new document.</p>
<p>{@img img5.png}</p>
<p>To set a CUSTOM field, the document template must be selected. CUSTOM fields can then be defined in the 'Additional information' tab. When creating new elements, the list is only displayed if at least one field has been defined with a name.</p>
<p>{@img img7.png}</p>
<h2>Automatic data transfer via placeholders</h2>
<p>Both the selected folder and the direct parent element are available in the template. Furthermore, all elements of the parent hierarchy can be accessed via <code>SOL_TYPE</code>.</p>
<p><span class="tag_caution">Due to technological restrictions, <span
style='font-weight:bold'>using mail merge is not recommended</span>. Instead, content controls should be used. These provide many more functions, such as date conversion, counters, localization keys, etc. and <span
style='font-weight:bold'>can be updated later on</span>.</span></p>
<h3>Microsoft Word content controls</h3>
<p>A number of predefined content controls are available for ELO Business Solution Contract in the form of <span
style='font-weight:bold;font-style:italic'>quick parts</span>. These can be downloaded from the <span
style='font-weight:bold;font-style:italic'>ELO SupportWeb</span>.</p>
<p>On the <span
style='font-weight:bold;font-style:italic'>Insert</span> tab in the <span
style='font-weight:bold;font-style:italic'>Microsoft Word</span> ribbon, you can then access most properties of the contract via the <span
style='font-weight:bold;font-style:italic'>Quick Part</span> function.</p>
<p>{@img img9.png}</p>
<p><span
style='font-weight:bold'>Importing ELO Business Solution Contract quick parts</span></p>
<p>Quick parts are transported using dotx Word templates. Microsoft Word manages a list of all components within the <span
style='font-weight:bold;font-style:italic'>Document Building Blocks</span> directory. The default components <span
style='font-weight:bold;font-style:italic'>Built-In-Building Blocks.dotx</span> are also located there. The path consists of the current user name and the Office version.</p>
<pre><code>C:\Users\-USERNAME-\AppData\Roaming\Microsoft\Document Building Blocks\1031\-Office Version-
</code></pre>
<p>This results in the following path for user name <span
style='font-weight:bold;font-style:italic'>MosbachN</span> using <span
style='font-weight:bold;font-style:italic'>Microsoft Office 2016</span>.</p>
<pre><code>C:\Users\MosbachN\AppData\Roaming\Microsoft\Document Building Blocks\1031\16\
</code></pre>
<p>For installation, the dotx file is filed to the directory above in the desired language (EN or DE). The quick parts of the contract can then also be accessed for new documents.</p>
<p>{@img img11.png}</p>
<h3>Manually creating Microsoft Word content controls</h3>
<p><span class="tag_important">The Microsoft Word Developer ribbon tab is required to add custom content controls. It contains a rich text content control as well as a plain text content control.</span></p>
<p>First, a new content control has to be added. To do this, select the <span
style='font-weight:bold;font-style:italic'>plain text content control</span> on the <span
style='font-weight:bold;font-style:italic'>Developer</span> tab. Next, the content control has to be configured. For this, open the control's <span
style='font-weight:bold;font-style:italic'>properties</span> dialog box.</p>
<p>The control's <span
style='font-weight:bold;font-style:italic'>title</span> serves only transparency and display purposes. A valid <span
style='font-weight:bold'>template expression</span> has to be entered as a <span style='font-weight:
bold;font-style:italic'>tag</span>.</p>
<p><span class="tag_important"><span
style='font-weight:bold;font-style:italic'>Information on templates:</span> To evaluate content controls, template expressions are used. These enable the use of date operations, conditions, etc. in Word. The class documentation <code>sol.common.Template</code> provides a list of all options.</span></p>
<p>{@img img13.png}</p>
<p><span
style='font-weight:bold'>Definition of a template expression:</span></p>
<p>The free handlebars.js library is used to evaluate template expressions. Information is therefore always accessed via <code>{{ .. }}</code> or <code>{{{ &hellip; }}}</code>. </p>
<p><span class="tag_warning">When accessing information, the 3x notation <code>{{{</code> should always be used because the data here cannot be escaped.</span></p>
<p>To provide all the information required to create the document, the entire hierarchy of a document is retrieved. This includes the corresponding <span
style='font-weight:bold;font-style:italic'>contract</span> (<code>CONTRACT</code>), the <span
style='font-weight:bold;font-style:italic'>contract structure</span> (<code>CONTRACT_STRUCTURE</code>), and the <span
style='font-weight:bold;font-style:italic'>contract document</span> (<code>CONTRACT_DOCUMENT</code>). Information is stored in ELO as <span
style='font-weight:bold;font-style:italic'>index fields</span> (<code>objKeys</code>) or <span
style='font-weight:bold;font-style:italic'>map fields</span> (<code>mapKeys</code>). </p>
<pre><code>{
  CONTRACT: {
    name: 'Short name',
    objKeys: {
      // Index fields
      CONTACT_LAST_NAME: 'Smith',
    },
    mapKeys: {
      // Map fields
      COST_CENTER_NAME: 'Accounting',
    }
  },
  CONTRACT_STRUCTURE: {
    name: 'Short name',
    objKeys: {    },
    mapKeys: {    }
  },
  CONTRACT_DOCUMENT: {
    name: 'Short name',
    objKeys: {    },
    mapKeys: {  
      CUSTOM1: '',
      CUSTOM2: ''
    }
  }
}
</code></pre>
<p>Some examples for accessing information:</p>
<ul>
<li>Last name of the contract partner: <code>{{{ CONTRACT.objKeys.CONTACT_LAST_NAME }}}</code></li>
<li>Name of the cost center for the contract: <code>{{{ CONTRACT.mapKeys.COST_CENTER_NAME }}}</code></li>
<li>Output custom field: <code>{{{ CONTRACT_DOCUMENT.mapKeys.CUSTOM1 }}}</code></li>
<li>Short name of the contract: <code>{{{ CONTRACT.name }}}</code></li>
<li>Date format: <code>{{ formatDate 'DD.MM.YYYY' CONTRACT.objKeys.CONTRACT_START }}</code></li>
</ul>
<h3>Microsoft Word mail merge</h3>
<p>In addition to the content controls, it is also possible to transfer data using the Microsoft Word mail merge function.</p>
<p>Mail merge fields can be created using the <span
style='font-weight:bold;font-style:italic'>Quick Parts &gt; Insert field</span> function (Microsoft Word 2016). Then, merge field has to be selected as the field type. </p>
<p>{@img img15.png}</p>
<p><span class="tag_warning">To make information accessible, all fields have to be surrounded by a merge field &laquo;TableStart:hierarchy&raquo; and &laquo;TableEnd:hierarchy&raquo;.</span></p>
<p>Then, contract information can be accessed between TableStart and TableEnd. </p>
<p>{@img img17.png}</p>
<p>Compared with content controls, a further level, <span
style='font-weight:bold;font-style:italic'>hierarchy</span>, is introduced. This is necessary since mail merge requires a start node. The start node is selected by an extra merge field, <span
style='font-weight:bold;font-style:italic'>TableStart</span>.</p>
<pre><code>{
  hierarchy: {
    CONTRACT: {
    },
    CONTRACT_STRUCTURE: {
    },
    CONTRACT_DOCUMENT: {
    }
  }
}
</code></pre>
<p>Some examples for<span
style='font-weight:bold;font-style:italic'> merge field field names</span> for accessing information:</p>
<ul>
<li>Last name of the contract partner: <code>CONTRACT.objKeys.CONTACT_LAST_NAME</code></li>
<li>Name of the cost center for the contract: <code>CONTRACT.mapKeys.COST_CENTER_NAME</code></li>
<li>Output custom field: <code>CONTRACT_DOCUMENT.mapKeys.CUSTOM1</code></li>
<li>Short name of the contract: <code>CONTRACT.name</code></li>
</ul>
