Editing of document templates in Word
General information about document templates
Since the focus is on the functionalities of MS Word, you can also use this information independently of the CURSOR application.
To efficiently and uniformly create and design documents using MS Word, document templates are used. Document templates or templates are marked with the extension .DOT (Word 2003) or DOTX and DOTM (Word 2007/2010). Best known is the template Normal.dot. If the user does not select a template when creating a new document, Word will default to this file.
Many document templates are usually designed so that documents based on them can be edited as easily as possible. They contain texts, tables, headers and footers, as well as elements that allow their content to be adapted quickly. The styles in these templates should also be well-organized so that the formatting of text, tables, etc. can be done safely and consistently.
Document templates in CURSOR-CRM
CURSOR Software AG uses document templates for the creation of documents. These contain a number of elements, such as:
Fixed text, for example contracts or quotes
Field functions to display the transferred fields
Field functions to further edit the information
Macros to further automate document creation.
Which of these elements are present in a template depends on the respective application.
The following chapters focus on the field functions. On the one hand, these form the link to CURSOR-CRM , because they are used to transfer and display the data in the document. As the field functions listed below show, it is also possible to define the behavior and appearance of the documents in a relatively simple way - without macro programming. Essential information about these field functions is provided in the following sections.
Fundamental for fields
For the output of variable content one uses the so-called fields in Word. These are also called field functions. Whether outline, page numbers, checkboxes or other elements whose contents can change: here such fields form the basis.
Fields consist of at least one pair of parentheses with a command expression. The easiest way to create the pair of brackets is to use the key combination CTRL and F9. Between the brackets you write the command that determines the function of the field. The following list shows a number of simple fields:
{ PAGE } | The current page number |
{ NUMPAGES } | The total number of pages of the document |
{ SECTIONPAGES } | The total number of pages in the current section |
{ CREATEDATE } | The date of the document creation |
{ TOC } | The structure (TOC = Table Of Contents) |
If you want to see the result of the field, you have to switch to the ‘result view’. This is done using the key combination ALT and F9. With this one switches between field function view and the result view (’toggle’).
To refresh the result, switch to the result view, select the field (or simply use CNTRL and Ato select the entire text) and then press the F9 key. As a result, an update takes place, then the newly calculated contents are in the fields. Fields in headers, footers or text fields must be updated separately. To do this, click on the header, footer or text box, then press CNTRL+A and thenF9..
For many fields, additional content, parameters and/or switches can be added. You then process this transferred information. For example, the field {= 3 + 4} calculates the number 7. Here information (3 + 4) is passed to the command “Calculate” (in the form of the equal sign). After updating with F9, the field returns the result 7 accordingly.
Important fields with such transferred information in CURSOR-CRM include:
{INCLUDETEXT [pad and file name] [bookmark]} | Returns the area defined by the bookmark from the specified file. |
{ DOCVARIABLE [Variable name] } | Displays the contents of the specified document variables |
{ DOCPROPERTY [Property name] } | Displays the contents of the specified document property |
Overview of the data transfer fields
The following sub-chapters explain the field functions that are used for data transfer from CURSOR-CRM : For individual documents, these are the SET and REF fields and the document variables using the DOCVARIABLE function. The data field with the ‘MERGEFIELD’ field function is used for the transfer for serial letter templates for letters and labels.
Data transfer via SET and REF fields
The field functions SET and REF are commands to which a value is transferred. They are the standard elements when transferring data to single documents in CURSOR-CRM.
SET and REF fields “work together”: The SET field assigns information to a named variable called a bookmark. For the information to be displayed in the document, there must be a REF field pointing to the bookmark. SET means “determine”, REF means “reference”.
SET fields form the backbone of the data transfer in CURSOR-CRM : Each entry in the mapping table in CURSOR-CRM is compared with such a field in the template. Therefore, at the beginning of the template is an often very extensive list of such SET fields.
These SET fields have the following appearance in the template:
{ SET GP_Name1 "GP_Name1" }
This means that the content ‘GP_Name1’, i.e. its own name, is assigned to the bookmark ‘GP_Name1’. In the document template, this bookmark can then be displayed via a REF function:
{ REF GP_Name1 }
In its place, the text ‘GP_Company1’ appears after switching (via ALT and F9) and refreshing (via F9). If a document is created with this template in CURSOR-CRM , the value from the CRM found by the complex search and transferred to the document via the mapping table / bookmark appears at this point, that is, the name of the business partner.
Data transfer via DOCVARIABLE fields
As already mentioned, the transfer of the data to the letter can also be done via document variables. For this, a corresponding entry must be made in the system settings.
The general notation of document variables is as follows:
{ DOCVARIABLE "GP_Name1" }
The advantage of these variables is that they are stored together with the document and therefore can be addressed at a later date (for example in macros). On the other hand, SET and REF fields are removed from the letter after data transfer.
Two document variables are automatically provided during document creation of individual and serial letters.
SYSTEM TYPE
This document variable contains the information from which system the document was generated (DEV, TEST or PROD). It can be used to represent different external text modules for development, test and production systems. The access to the corresponding subdirectory of the text modules is done by customer-specific VBA logic. This means that test changes to the text module of the development system would not be visible in the production system.SYSTEM NAME
This document variable contains the name of the system from the Customizing transport settings section of the system settings. It offers a further degree of liberty to map different external text modules, e.g.: different product lines.
Data transfer via MERGEFIELD fields for serial letters
Form letters are created in CURSOR-CRM in the usual way for such letters: a data source is created, which is then automatically linked to the letter. The template contains fields that use the MERGEFIELD function to access the values in the corresponding column of the data source:
{ MERGEFIELD GP_Name1 }
The name of the field is generated by CURSOR-CRM. To find out the names of these errors, the easiest way to create a serial letter via a test run is to look at the data source in Word or to insert fields from that data source into the document using the usual buttons. An essential role in serial letters is played by the field function NEXT. With their help, you can jump to the next dataset without page changing. That’s what you need when it comes to designing label templates. In this case (starting with the second label) the field 'NEXT' is placed at the beginning of the address range.
Buttons and formatting instructions
Before we turn to further field functions, the effects of the field buttons should be described here. Many fields have such buttons. They can also be inserted into the parenthesis pair and influence the behavior of the field. Buttons are behind the commands and information and always start with a backslash (”\”). This is followed by a character representing the button. The button itself can in turn be added more information.
Format button
The buttons most commonly used in CURSOR-CRM templates are the formatting buttons: they affect the appearance of the field result. The default case looks like this:
{ REF GP_Name1 \*CHARFORMAT}
The character “*” stands for the button “format button”. The word CHARFORMAT is then the actual statement: it specifies that the field result is formatted as the first letter in the field, hence the letter “R” of the word REF.
The following list contains important format buttons:
\*CHARFORMAT | Formats the field result corresponding to the formatting of the first letter in the field. |
\*UPPER | Converts all letters of the field result into capital letters |
\*CAPS | Converts the first letter of the word of the field result to uppercase letters |
\*CardText | Shows a number as text: “12” becomes “twelve” |
\*OrdText | Displays a number as an ordinal number in text form: “12” becomes “twelfth” |
You can also combine such buttons. The character formatting button should always come last.
Example:
{ = 12 \*Cardtext \*lower } | twelve |
{ = 12 \*Cardtext \*upper } | Twelve |
Button for numerical format
Instructions for formatting numeric field results start after the “\” with a #. This character is followed by an instruction that specifies, for example, thousands, comma, decimal places, and so on.
Examples:
{ = 1234567,678 \# # } | 123457 Decimal places are omitted, number is rounded |
{ = 1234567,678 \# #.###,## } | 1234567.68 All thousands of points are displayed, number is rounded to 2 decimal places |
{ = 1234567,1 \# #,00 } | 1234567.10 The “0” also returns values(i.e. 0) if the number has no value at this point. The # does not have this effect. |
Further buttons can be found in the online help.
Date/time format button
Date and time can be formatted using the “@” button. Next, as with numeric buttons, are instructions that set the appearance of days, months, years, hours, and so on.
Examples:
{ QUOTE "06.07.2011" \@ "dd.MM.yyyy" } | 06.07.2011 Double typing “d” (for Day) and “M” (for Month) leading zeros. You have to enter a big “M” here, because the small “m” gives the minute of the time |
{ QUOTE "06.07.2011" \@ "d.M.yy" } | 6.7.11 Short presentation, no leading zeros, year only two digits |
{ QUOTE “06.07.2011” \@ “’Giessen, 'd. MMMM yyyy" } | Giessen, 6th July 2011 One must note the use of single quotes to insert fixed text into the button. |
You can also find additional important instructions in the online help for this.
Important field functions and their design
The following chapters describe some of the key features of CURSOR-CRM. They are not exhaustive, so you should always use Word’s online help and related pages on the Internet as a source of information.
Of great importance are functions that allow a comparison. These include the IF and COMPARE instructions as well as the AND and OR operators: they can also be used to represent multiple branches. Texts such as the GTC or other general information can be maintained in one place and then inserted at runtime in the document created: there is the function INCLUDETEXT.
The IF-condition
IF conditions are used when the output of the field is to be made conditional. The function has the following general appearance:
{ IF Bedingung "Dann-Fall" "Sonst-Fall" }
The condition is introduced with the word IF, the Then and the Else case are enclosed in quotation marks.
Example 1:
The business partner type has an impact on the design of the address block. In order to ensure the right appearance, depending on the type, the GP_Type is checked and displays either the “Then” or the “Else” branch according to the content. For the example with the business partner type, for example:
{ IF GP_Typ_K = "U" "Firma" "Herrn/Frau" }
Example 2:
The address header uses IF conditions to prevent blank lines caused by one or more of the bookmarks having no content. This usually affects the bookmarks with names like GP_Name2 and GP_Name3. The IF condition checks whether the bookmark contains a value. If so, the bookmark is output and then a line break is executed. If, on the other hand, no data has been transferred to the field, no line break is made. This is achieved by the following statement:
{ IF { REF GP_Name2 } <> "" "{ REF GP_Name2 \* CHARFORMAT}¶" ""}{ IF { REF GP_Name3 } <> "" "{ REF GP_Name3 \* CHARFORMAT}¶" "" }
The COMPARE instruction
The COMPARE instruction has the following general appearance:
{ COMPARE Ausdruck1 Vergleichsoperator Ausdruck2 }
It returns the value 1 if the comparison is true, otherwise it returns a value other than 1 (usually 0). This function is mostly integrated into IF conditions.
Example:
The instruction
{ COMPARE { REF GP_Typ_K } = „U" }
Returns 1, if the business partner has type “U” for company. The above shown IF condition can also be written as follows:
{ IF { COMPARE { REF GP_Typ_K } = "U" } = 1 "Firma" "Herrn/Frau" }
In addition, with COMPARE you can also use the “*” for any number of characters and the “?” for exactly 1 character. In this case, the expression1 must also be enclosed in quotation marks so that it is interpreted as text.
The following instruction returns 1 if the transferred postal code begins with the values 35
{ COMPARE "{ REF ADR_PLZ }" = "35*" }
The AND and OR operators
The benefits of the COMPARE function can be increased even further with the AND and OR operators. The general notation is as follows:
{ = AND (<COMPARE-Funktion1>;<COMPARE-Funktion1>) }
or
{ = OR (<COMPARE-Funktion1>;<COMPARE-Funktion1>) }
It returns either the value 1 or the value 0 according to the logic of linking.
The comma is entered in the Word Online documentation as a separator between the two instructions to be checked. In the German locale a semicolon must be used here! Otherwise, the function does not work. So you can make two comparisons in one step and determine whether only one of the fields (”OR”) or both fields (”AND”) must fulfill the condition.
An example in CURSOR-CRM is the design of the address header:
{ IF { = AND ({ COMPARE { REF GP_Typ_K } = "U" } ; { COMPARE { REF AP_Typ_K } <> "U" })} = 1 "{ REF AP_Anrede \*charformat}" "" }
This instruction means: The field ‘AP_Salutation’ is only displayed if the business partner is a company and at the same time the contact person is a natural person.
The INCLUDETEXT instruction
With this instruction you can store a reference to a text from another file. This is very useful for standard elements in the templates, such as the address header: instead of entering a header in each template, you place it centrally in a file and then insert only an INCLUDETEXT reference in each template.
This looks something like this:
{INCLUDETEXT "U:\\EVI\\DOK\\VORLAGEN\\Textmarken_Allgemein.DOC" KOPF1 }
The double backslashes are necessary for this way of specifying the path!
The entry HEADER1 refers to the fact that in the file Textmarke_Allgemein.DOC the address header has been marked with a bookmark “HEADER1”. So you can store a lot of text blocks in a file and then specify what is required via the underlying bookmark. Scanned signatures can also be brought into the document via this function. To do this, you first set it in the central file as a graphic and provide it with a bookmark name. This name consists of the abbreviation of the employee, preferably with a fixed letter (e.g. “U_”) before: “U_HTC”
In the document template you now deposit the include text statement in the following form:
{INCLUDETEXT "U:\\EVI\\DOK\\VORLAGEN\\Textmarken_Allgemein.DOC" "U_{ REF MA1_Kuerzel }" }
This will give you the appropriate signature at this point.
The possible path via the INCLUDEPICTURE function is not suitable, because here the pictures come in their original size in the document.
Access to document properties
In addition to the document variables mentioned above, there is a second type of information carrier: the document properties. They are accessed in the following form:
{ DOCPROPERTY "CU_INCLUDEPATH" }
In this case, the document property ‘CU_Includepath’ contains the path to a file whose contents are to be embedded in the document. As a whole, the condition for embedding an address header, for example, would be as follows:
{ INCLUDETEXT "{ DOCPROPERTY "CU_INCLUDEPATH" }" "Adresskopf1" }
Above all, in conjunction with document properties inserted via the text replacement file, there are many possible uses for such elements.
Combinations of the functions shown
In most cases, the field functions in the document templates are relatively short. However, you can combine these functions with each other and combine them into large units. For example, the SET condition can be combined very well with the IF functions. An example: in the template, a salutation is required at various points, which depends on whether the contact person is a woman, a man or a legal person. So that you do not have to check this repeatedly in the concerned areas using a large IF condition, you put a SET command at the beginning of the document, which then depending on the content of the text contains either “Dear Madam”, “Dear Sir” or “Dear Ladies and Gentlemen”:
{ SET LocAnrede "{IF { COMPARE { REF AP_Typ_K } = "U" } = 1 "Sehr geehrte Damen und Herren" "{IF { COMPARE { REF AP_Typ_K } = "F" } = 1 "Sehr geehrte Frau" " Sehr geehrter Herr" }" }" }
At the output points, one then only writes the REF-field to the variable LocAnrede. The letters “Loc” are intended to indicate that this is a locally generated variable that has not been transferred from CURSOR-CRM. A disadvantage of this solution is, unfortunately, that after the current behavior of the application, the commands “Convert and edit with (or without) Ref” remove such self-created SET fields from the template. Nevertheless, it is a sensible solution to increase the clarity in the template.