How to create a Template (Word Document)

A good starting point would be to download an existing template in the system to see how it all works.

To download an existing template:

1) Go to System Template Entry

 2) Templates that are written in the new Word Format, will have a Word Icon next to it, to allow you to download the Word Document Template. 

I have selected to download 'Standard V1.9'.

You should notice that the template is full of "Merge" fields. The system will take the merge fields and replace them with the relevant data.

A list of the fields available per Template Type can be downloaded as an XML file from System Template Entry by clicking the following icon.

This file can be opened in a Web Browser, or in a text editor such as Notepad

Some available fields have a prefix; you can find the meaning of these Prefixes by reading:

XLM Field Prefixes article

You will need to have customized your Word layout to be able to insert Merge Fields, if you have not, then you can do so by following the steps in – Set up Word to Create a Template 

A template document requires extra Merge Fields, which do not get rendered out, but the system uses to know where to put and find fields. These do tend to mess up the look of your Word Document as you edit it, so to minimize this; we have made the text of these fields as small as possible (1pt).

You will notice in the example I downloaded, there is a small field at the top left of the page and to the left, just underneath the totals of the Invoice.

These are a good example of very important fields, required to make this Template work, but do not get drawn onto the final document. If we highlight these fields and enlarge the text size, so that we can read them, you will notice why these are important.

These indicate to the system that all the fields in between them, that they come from the area of the XML file inside the "Invoice" XML tag. So, if you were to download the PayInvoice XML example to create a PayInvoice Template, you would change these to be TableStart:PayInvoice and TableEnd:PayInvoice.

You can edit any field, if it exists; by right clicking on the Merge Field and selecting Edit Field (It doesn't work to just change the text on the page). You can then change the Field Name and click OK.

If you need to insert a basic Merge Field, you can select anywhere in the Word Document that you want the field to go (as long as it is between your TableStart and TableEnd tags), click on Insert from the menu, and click Field from your Merge Group that you have added to your Word Layout (See above for article on how to do this).

With the field box open, select MergeField from the Field names and enter the Field name that you want to display, from your Example XML file, and click OK.

Advanced 
Some of the Available XML Elements, ones that have children, require a bit more work in Word, to display properly.These require at least 6 Merge Fields in Word to display properly, but follow the same rules as the opening and closing Merge Fields for the overall document.

Let’s say you have the following in the XML File. 

You would first need to create TableStart and TableEnd Fields of Parent XML Element, then you can place and Merge Fields that you want to display from this parent element inside the TableStart and TableEnd. So you would end up with the following...

As I mentioned before, these TableStart and TableEnd tags don't get rendered out on the final document, but the system needs these to know where to find CaFullName. In this case, Inside the XML Element Invoice, inside the Element FirstCandidateTimesheet, there is a field called CaFullName.

These table tags can ruin the look of the document as you are trying to design your word document, so I suggest highlighting them and making them as small as possible. Like the example below. CaFullName will render out as the far left of the document on that line, irrespective of what you are seeing in Word.

You can place as many Merge Fields between the TableStart and TableEnd as you wish. You can place any Word object such as Textbox and Table etc. and they can all contain fields from the XML Region defined by your surrounding TableStart and TableEnd Tags. The only caveat to this is that the TableStart and TableEnd fields must be in the same parent region of the word document.

For example, you could not create a word table, and on row 1, place your TableStart field, then place a field on a new row, and then place your TableEnd field in the bottom row. To achieve this you would have to place your TableStart and TableEnd fields outside your word table.

Any XML Element that has multiple child parent elements, such as the TBillCostList field, takes a little more work.

The above rules work in this example, except you need some more fields to dive deeper into the XML. If there are multiple elements inside here, like TBillCost has 2 TimesheetCost elements, the system will automatically repeat these on the word document on new lines, or, if you have use a word table, new rows.

Here is how to set up the Word Document to output the TBillCostList into a word table from FirstCandidateTimesheet

This is saying, inside the XML Element FirstCandidateTimesheet, inside the XML Element TBillCostList, inside each XML Element TimesheetCost, create a word table row with the Rate, Units and Total. In this example XML, this will render out 2 lines as there are 2 TimesheetCosts in the TBillCost List.

The best way of thinking about this is a TableStart field is the same as an XML opening tag and a TableEnd field is the same as an XML closing tag, when we are talking about parent XML Elements.

Don't forget, that you can then highlight your TableStart/TableEnd fields, and make them as small as possible so they don't get in the way of your design.

Merge Field Formatting

You may wish to do some formatting of data in the merge fields when Word displays them, such as formatting dates or numbers to decimal places.

To add formatting to a field, right click on the field, and select Toggle Field Codes. This will display the underlying code for your merge field. and it will look something like this.

 

Now you can add some formatting, some of which are listed in the table below. This is a date and I want to format it out as 01 DEC 2012, so I can modify the code to be the following.

Once you have finished, right click the field again and click Update.

Here are a list of some of the options and examples.

There will be times when you want to do some conditional merging. This is achieved in a similar fashion, but requires a little more word coding.

For example, if you want to change the header of your Invoice to say Credit Note, if the Total of the Invoice is negative.

First, select where you want to put your header, then press F9. This should insert a {  } as below

You may notice this is what is displayed when you select Toggle Field Codes on a merge field to do the formatting examples above...

Inside the Curly Braces, you can write some conditional logic, so for our example, we want the following..

To get the extra {} inside for the MergeField, press F9 again and this will insert a new set of Curly Braces, inside which you can define a MERGEFIELD TotalField, which is what word creates for you when you use the menu to insert a merge field.

So, when the TotalAmt is 0 or greater, then we want INVOICE to be displayed, otherwise we want CREDIT NOTE to be displayed.

{ IF Condidtion "True" "False" }

You can also display Mergefields in the True and False output sections, by again, pressing F9 in the relevant section and declaring MERGEFIELD name

Eg

{ IF { MERGEFIELD TotalAmt } >= 0 "{ MERGEFIELD ClName }" "{ MERGEFIELD AgName }" }

This will show the Client Name if the TotalAmt is 0 or greater, otherwise it will show the Agency Name.