Embed Size (px)
Citation preview
ZumeSoft Solutions Pty Ltd
Designing Document Templatesfor ZumeFormsThis document will assist you build document templates in Microsoft Word for ZumeForms
16June
Index
1 An introduction to advanced Microsoft Word™...........................................................41.1 Setting up Microsoft Word™.............................................................................................................................41.2 Mergefields...............................................................................................................................................................51.3 Automatic clause and paragraph cross-references................................................................................61.4 Bookmarks............................................................................................................................................................... 61.5 Styles........................................................................................................................................................................... 61.6 Custom numbered paragraphs........................................................................................................................71.7 Document and paragraph settings and rules............................................................................................71.8 Setting up your preferences and views.......................................................................................................8
2 Automating a Document Template..............................................................................8
3 Adding content from Form Fields using ‘mergefields’...................................................9
4 Field types...................................................................................................................94.1 Text Fields..............................................................................................................................................................104.2 Yes/No Fields.......................................................................................................................................................104.3 Choice Fields.........................................................................................................................................................104.4 Number Fields......................................................................................................................................................104.5 Date Fields............................................................................................................................................................. 114.6 Script Fields...........................................................................................................................................................11
5 Formatting content with common Field Switches.......................................................115.1 Letter formatting Switches.............................................................................................................................115.2 Leading and following Switches...................................................................................................................115.3 Date Switches.......................................................................................................................................................125.4 Dollar formatting................................................................................................................................................135.5 Number words.....................................................................................................................................................135.6 Alphabetic text.....................................................................................................................................................145.7 Roman text.............................................................................................................................................................145.8 Masks....................................................................................................................................................................... 14
6 Using Microsoft Word fields.......................................................................................166.1 Inserting a date without a ZumeForms field..........................................................................................166.2 Creating a number sequence.........................................................................................................................166.3 Page numbering fields......................................................................................................................................176.4 Formula (Calculation) Fields.........................................................................................................................18
7 Conditional content...................................................................................................197.1 An <IF> statement with a Yes/No field:....................................................................................................207.2 An <IF> statement with a Choice Field:....................................................................................................207.3 An <IF> statement with a Choice Field when a choice ‘IS NOT’ made:.......................................217.4 An <IF> statement with a Number Field:.................................................................................................217.5 Insert content if a Field is blank or empty:..............................................................................................227.6 Insert content if a Field is one thing OR another Field is another thing:...................................227.7 Insert content 2 or more conditions are met:........................................................................................237.8 Some common mistakes with conditional content..............................................................................23
8 Conditional Field content – Short-IFs..........................................................................24
Page 2
8.1 Inserting a checkbox outcome into a Document...................................................................................25
9 MergeText.................................................................................................................259.1 MergeText Values on fields............................................................................................................................259.2 MergeText Lists...................................................................................................................................................26
10 Multi-row or table data..........................................................................................2810.1 The <Table> statement....................................................................................................................................2810.2 Conditional table content................................................................................................................................2910.3 Repeats within a MS Word table..................................................................................................................2910.4 Count repeats....................................................................................................................................................... 2910.5 Accessing a field one level above a repeat...............................................................................................30
11 ZumeForms Switches..............................................................................................3011.1 WF:DelEmptyPara..............................................................................................................................................3011.2 WF:DelRow............................................................................................................................................................31
12 List Formattting......................................................................................................32
13 System User fields..................................................................................................33
14 Standard template components.............................................................................3414.1 Person details.......................................................................................................................................................3414.2 Standard address – multi-line.......................................................................................................................3414.3 Standard address – one line...........................................................................................................................34
Page 3
Template DesignThis document will assist you build templates in Microsoft Word for ZumeForms.
1 An introduction to advanced Microsoft Word™We have adopted Microsoft Word as our template-building program because in our view is it the most advanced and widely used word processor available. That said, many of the features of Word that are used in Document Templates may not be familiar to even a regular user.
You may wish to engage a professional Microsoft Word user to assist you complete your Document Templates with each of the following elements to ensure a consistent end product. We are able to assist with this process.
Set out below is a brief explanation of some of the more common Microsoft Word functionality that is used in document automation.
1.1 Setting up Microsoft Word™
1.1.1 Downloading the Word add-inZumeForms has an ‘add-in’ that assists in the design of your templates. The add-in extends the functionality of Word to include special ZumeForms functions.
This add-in is only available for Microsoft Windows users using MS Word 2010 or above on a Microsoft Windows machine (sorry Mac users!).
We recommend that you download and install this add-in as it will assist you design and trouble-shoot your templates. This add-in can be downloaded here: http://zumeforms.com/Files/Deploy/ZumeForms/MicrosoftWord/setup.exe
1.1.2 Exposing mergefield contentsBefore you start we recommend that you set up Word so that you can see the content of the fields and other properties that you are entering into the document.
If you are using Word on a Mac then you go to Word/Preferences/View/ and check ‘Field codes instead of values’
Page 4
You may also want to set a similar setting for when you print the document – so you can see the field codes rather than the values.
If you are using Word on a Mac then you go to Word/Preferences/Print/ and check ‘Field codes’
1.2 MergefieldsPerhaps the most important element of Word for document automation is the mergefield. A mergefield is a native MS Word field that is inserted into the Document Template when it is being designed, and which is then either:
Replaced with ‘content’ entered by the user when the Document is assembled; or Activates code to change elements of the document, e.g. removing conditional content
using an <IF> statement.
Mergefields can have ‘Switches’ included in them that control elements of the content within the mergefield, e.g. by making all of the content capitalised, or changing the presentation format of numbers.
Mergefields are discussed further at paragraph 3 below.
Page 5
1.3 Automatic clause and paragraph cross-referencesOften document automation is used to automate a document (e.g. a legal agreement) that is made up of numbered clauses or paragraphs. Furthermore, many documents rely on one clause referring to another clause by number, e.g. “Clause 1: Subject to the condition in clause 3, this clause say [ABC]..” The reference to clause 3 in clause 1 is a clause reference.
The potential issue with clause references is that they can get out-of-sync if the document automation process removes clauses or adds clauses in between the main clause and the referenced clause.
The issue of out-of-sync clause references is dealt with by using automatic paragraph Cross-references. The Cross-reference inserts a native MS Word Field into the document that is hard-coded to refer to a particular paragraph’s content in the document, irrespective of its number. When the numbers of each paragraph change, the Cross-reference is updated to continue to refer to the correct document content.
You often need to update all of the Cross-references in a document prior to printing. This can be done by selecting all of the Document’s content (Control-A/Command-A), and then by pressing Function Key (F9). This will also update any other Field content and Document elements, such as Tables of Contents, etc.
This is an example of a Cross-referenced field:
1. This is a Cross-reference to line 3 in this example.2. This is the second line of the example.3. This is the third line of the example.
You can delete line 2 of this example and then update the fields [F9] and you will see that it now refers to line “2”.
1.4 BookmarksA Bookmark is content within a Document that can be referenced in another part of the Document. The content is ‘bookmarked’ by an MS Word function, and a copy of that content can then be inserted into the Document by using a Cross-reference to that content. This can be handy when you want to refer to a heading in another part of the Document, e.g. the title of a schedule to an agreement.
This is the book-marked text. Notice the close-brackets around the text. A Cross-reference to the text looks like this: This is the book-marked text.
1.5 StylesUsing Styles in Microsoft Word is very important to ensure that your end Document has a consistent and professional look. Basically, a Style is a set of rule about how the content of a
Page 6
Document is going to be formatted and set out. In our view, every bit of content within your Document Template should have a Style element applied to it.
You can adopt Styles that are native to Word (i.e. what applies when you first open a blank document in Word), or which belongs to a particular Style set (or Theme) included with Word. You can also adopt your own Styles and create new ones as you need them.
This guide has been prepared using native Word Styles associated with a native Word Theme. This is an example of a number of lines to which difference Styles have been applied:
Subtitle
Subtitle emphasis
Emphasis
Intense Emphasis
Strong
Quote
1.6 Custom numbered paragraphsIf your document is a legal agreement, then most of the paragraph will be numbered into clauses. Numbers should be automatically applied to paragraphs, rather than ‘hand-written’ by the person preparing the numbers. This will facilitate automatic updating of the numbered paragraphs themselves, as well as any Cross-references to the numbered paragraphs.
Word has both simple ‘numbering libraries’, as well as custom numbering and ‘list’ libraries. The numbered paragraphs of this guide are an example of a custom numbering list that has been applied to each heading and sub-heading.
1.7 Document and paragraph settings and rulesWhen a Document is automated the person designing the Document Template does not necessary know what the final Document is going to look like when it is assembled by the User. This is because the User will make choices that determine what content is assembled into the document, including what paragraphs are included and excluded. For this reason, it is not possible for the Document Template designer to predict things like where page breaks are inserted, and paragraph placement.
In order to avoid ‘orphan paragraphs’, and headings being on one page with the content on the next page, it is possible to set rules for how content will be displayed if certain conditions are met. The most common is to set rules for the formatting of the Document and paragraph.
1.7.1 Keep with nextThis is a paragraph formatting rule, and it is often applied to headings. This ensures that the heading is not left on one page with the content of the following paragraph on the next page.
Page 7
1.7.2 Window/orphan controlThis is a paragraph formatting rule, and it will ensure that a page does not start with only one line of the paragraph started on the page before. It will ensure that at least two or three lines of the paragraph are included on the next page.
1.8 Setting up your preferences and viewsFinally, it is a good idea to set up Microsoft Word preferences and views to assist you in the Template Document design process.
1.8.1 Field code and contentBecause you will be working a lot with Fields and their code and contents, we recommend that you familiarise yourself with the display preference that enables you to toggle between displaying the Field code and content.
If you are working with a Document Template that is displaying the Field content, then you can ‘toggle’ the individual Field to display the Field code by right-clicking on the mouse over the Field and selecting ‘toggle field codes’.
We also suggest that you turn on ‘field shading’ so that you can see what elements of the Document Template are fields.
2 Automating a Document TemplateIn our view, the best place to start when automating the production of a document is with the Document Template itself.
Start by replacing any content that will be collected through the Form with ‘mergefields’ in the Document Template. This is similar to what you would do if you were using the native ‘Merge Documents’ functionality of Microsoft Word.
For example, if the Document Template were a standard letter, you would replace the salutation section as follows:
Dear «Name_First» «Name_Second»
TIP: The \* MERGEFORMAT switch is automatically included with each mergefield. The effect of this switch is to ensure that the formatting of the content inserted by the mergefield matches the formatting of the relevant section of the Document Template. This can be removed, or overridden by other switches (as discussed later). For now, we recommend leaving this switch in place. However, most power-users prefer to remove it, as it can make the template harder to read and trouble-shoot.
When you have replaced all of the content in the Document Template with mergefields (and other document automation elements), it is time to build the Form Template within Zumeforms.
Page 8
A common mistake that people make is to start with the Form Template, and then look to slot each of the Form Fields into the Document Template. This can result in Form Fields that are unnecessary, and other Document Fields that have not been included in the Form. Given that you are aiming to produce the Document as the end result, it is the best place to start the automation process.
3 Adding content from Form Fields using ‘mergefields’The simplest concept in document automation is inserting content from a Field on a Form into a Document Template.
This is done by including a mergefield into the Document Template with the same field name as is used in the Form Template:
«Field1»
You can include a Field in more than one place within the Document Template, i.e. you can use it as often as is required.
4 Field typesThere are several different Field types that will assist you manage different content.
The first thing to note is that the Form into which the User enters data will be made up of a number of Form Fields. When you design a Form on ZumeForms the Form Builder gives you are number of options for Form Fields:
Page 9
The Document Fields (or Fields) discussed in this guide relate to each of the Form Fields. This is because the Document Fields need to accept (or deal with) the content or selections made by the User when entering data into the Form.
When designing a Document Template we generally refer to the following Field types:
4.1 Text FieldsThese fields contain text that the User enters into a text Field on the Form. This can be single or multiline. (We usually notate the field with “_txt” at the end of the field name so we remember what type of field it is.)
4.2 Yes/No FieldsThis is a simple logic field that is either ‘true’ or ‘false’. This Field matches the Check Box Form Field. (We usually notate the field with “_yn” at the end of the field name so we remember what type of field it is.)
4.3 Choice FieldsA Choice Field contains the content of the User’s choice on a Dropdown List, List Box or Radio Button Field on the Form. A Choice Field can contain a single piece of data (i.e. a single choie), or multiple pieces of data, separated by a “|” symbol. (We usually notate the field with “_cho” at the end of the field name so we remember what type of field it is.)
4.4 Number FieldsA number field is a field that contains a number. This is distinguished from a field containing text, so that particular number formatting Switches can be applied to the Field without concern
Page 10
that the Switch will not properly act on the text. (We usually notate the field with “_num” at the end of the field name so we remember what type of field it is.)
4.5 Date FieldsA Date Field is a field that contains date and time information. A Date Field is distinguished from a Text Field so that it can be subject to the formatting Switches that are available for date formats. (We usually notate the field with “_dt” at the end of the field name so we remember what type of field it is.)
4.6 Script FieldsA ‘Script Field’ is a special type of ZumeSoft field that contains the outcome of a ‘script’ or calculation. They can also contain the outcome of a logical function, i.e. they can be ‘true’ and ‘false’. (We usually notate the field with “_scr” at the end of the field name so we remember what type of field it is.)
5 Formatting content with common Field SwitchesA Switch is a thing that changes the format or action of Field content. For example, a Switch can make all of the Field’s contents into capital letters, format a date, or it can format the content into a given number.
5.1 Letter formatting SwitchesThese switches change the capitalisation of Field content:
«Content_txt»: This will make Content
«Content_Txt»: This will make Content
«CONTENT_TXT»: This will make CONTENT
«content_txt»: This will make content
5.2 Leading and following SwitchesThese Switches enable you to include content before or after the Field’s contents. This can be useful to provide the leading wording, or trailing wording, that is appropriate to a Field in a particular context:
Page 11
«Text_txt»: Text_txt – following -
«Text_txt»: - before- Text_txt
«Text_txt»: - before – Text_txt – following -
5.3 Date SwitchesThese switches change the format of a date Field:
«DATE_dt»
«DATE_dt»
You can also include words within the switches as follows:
«DATE_dt»
Some common date formats:
Page 12
5.3.1 Inserting a date without a ZumeForms fieldTo insert the date into your document without a field:
{ DATE } - The date you are looking at the document. Always today (although it may not show on screen as today until you update the field).
{ CREATEDATE } - The date the document was created (or saved using Save As). { PRINTDATE } - The date the document was last printed. { SAVEDATE } - The date the document was last saved.{ DATE }
5.4 Dollar formatting
«Number_num» - dollars with no cents.
«Number_num» - dollars and cents.
«Number_num» - dollars and cents
5.5 Number wordsThis switch changes a number into words, e.g. "101" to "one hundred one". (You control the capitals with another switch following the CardText switch.)
«Number_num»
Page 13
5.6 Alphabetic textThis switch changes a number into the corresponding alphabet letter:
«Number_num»
For example, as used in a sequence, {SEQ appendix \ * Alphabetic} gives a result of "B" instead of "2.".
5.7 Roman textThis switch changes a number into the corresponding roman alphabet letter:
«Number_num»
For example, as used in a sequence, {SEQ appendix \ * Roman} gives a result of "II" instead of "2.".
5.8 MasksYou can format the content of a Field using a ‘mask’:
«Field_num_msk»
Some of the more common masks include:
0 (zero) Specifies the requisite numeric places to display in the result. If the result does not include a digit in that place, Word displays a "0". For example, { = 4 + 5 \# 00.00 } displays "09.00".
# Specifies the requisite numeric places to display in the result. If the result does not include a digit in that place, Word displays a space. For example, { = 9 + 6 \# $### } displays "$ 15".
x Drops digits to the left of the "x" placeholder. If the placeholder is to the right of the decimal point, Word rounds the result to that place. For example:
{ = 111053 + 111439 \# x## } displays "492".{ = 1/8 \# 0.00x } displays "0.125".{ = 3/4 \# .x } displays ".8".
. (decimal point) Determines the decimal point position. For example, { = SUM(ABOVE) \# $,0.00 } displays "$495.47".
Note: Use the decimal symbol specified as part of the regional settings in Microsoft Windows Control Panel.
, (digit grouping symbol)
Separates a series of three digits. For example:
Page 14
{ = NetProfit \# $#,###,### } displays "$2,456,800".
This can be written more simply as { = NetProfit \# $,0 }
Note: Use the digit grouping symbol specified as part of the regional settings in Windows Control Panel.
- (minus sign) Adds a minus sign to a negative result, or adds a space if the result is positive or 0 (zero). For example, { = 10 - 90 \# -0 } displays "-80" and{ = 10 + 90 \# -0 } displays " 190".
+ (plus sign) Adds a plus sign to a positive result, a minus sign to a negative result, or a space if the result is 0 (zero).
For example,
{ = 100 - 90 \# +0 } displays "+10"
and
{ = 90 - 100 \# +0 } displays "-10".
%, $, *, and so on Includes the specified character in the result.
For example,
{ = netprofit \# "##%" } displays "33%".
"positive; negative" Specifies different number formats for positive and negative results. For example, if the bookmark Sales95 is a positive value, the field
{ Sales95 \# "$,0.00;-$, 0.00" } displays the value with regular formatting— for example, "$1,245.65".
A negative value is displayed with bold formatting and a minus sign— for example, "-$ 345.56".
"positive; negative; zero"
Specifies different number formats for a positive result, a negative result, and a 0 (zero) result. For example, depending on the value of the Sales95 bookmark, { Sales95 \# "$,0.00;($, 0.00);$0" } displays positive, negative, and 0 (zero) values as follows: $1,245.65, ($ 345.56), $0
'text' Adds text to the result. Enclose the text in single quotation marks.
For example,
{ = { Price } *8.1% \# "$,0.00 'is sales tax' " }displays "$347.44 is sales tax".
'numbereditem' Displays the number of the preceding item that you numbered by using the Caption command (Insert menu, Reference submenu) or by inserting a SEQ field. Enclose the item identifier, such as "table" or "figure," in grave accents (`). The sequential number is displayed in Arabic numerals.
Page 15
For example,
{ = SUM(A1:D4) \# ",0.00 'is the total of Table' `table`" }displays "456.34 is the total of Table 2".
For further information on native Field Switches in Microsoft Word, see http://office.microsoft.com/en-us/word-help/insert-and-format-field-codes-in-word-2010-HA101830917.aspx.
6 Using Microsoft Word fieldsFields in Word are used as placeholders for data that might change in a document and for creating form letters and labels in mail-merge documents.
For a full list of useful Word fields, see here: https://support.office.com/en-us/article/Field-codes-in-Word-1ad6d91a-55a7-4a8d-b535-cf7888659a51?ui=en-US&rs=en-US&ad=US
6.1 Inserting a date without a ZumeForms fieldTo insert the date into your document without a field:
{ DATE } - The date you are looking at the document. Always today (although it may not show on screen as today until you update the field).
{ CREATEDATE } - The date the document was created (or saved using Save As). { PRINTDATE } - The date the document was last printed. { SAVEDATE } - The date the document was last saved.{ DATE }
6.2 Creating a number sequenceA Sequence field tracks differently numbered lists within a document.
The syntax is as follows:
{ SEQ identifier [bookmark ] [switches ] }
The identifier is a unique to the sequence. You need to specify a separate identifier for each sequence. For example, you could create a sequence for number Schedules: {seq Schedules} and then another separate sequence for numbered items within a schedule {seq Items}.
The identifier must start with an alpha character and be 40 characters or less. You can use alpha and number characters and the underscore character to complete the name.
Use bookmark to refer to an item somewhere else in the document. In addition, the following switches add flexibility.
Page 16
If you want to start the numbering over again:
{ seq identifier \r1 }
The addition of the \r1 switch causes Word to start the sequence counter over at 1. You would use this whenever you wanted to start a new list, and use the regular field for the rest of your numbered items. (If you want to start the list over at a number other than 1, use the starting number right after \r.)
6.3 Page numbering fieldsWord has four fields that work for page numbers:
{PAGE} - In its simplest form this will display the page number, numbered from the beginning of the document. You can format any of the page number to display in Roman numerals (upper- or lower-case), Arabic numerals, or as text. You can restart the page numbering anywhere you want; doing so will insert a new Section if you are not already at the start of a new Section.
{NUMPAGES} - The NUMPAGES field reports the total number of pages in the document. Unlike the PAGE field, it is not possible to restart the numbering of the NUMPAGES field.
{SECTIONPAGES} - The SECTIONPAGES field reports the total number of pages in a Word Section. A document must have at least one Section and can have many. It is often used to number Appendices in a document.
You can format the page numbers with the following switches:
Page 17
6.4 Formula (Calculation) FieldsA formula field is one that does some kind of calculation and shows you the result. It starts with an equals sign.
Syntax:
{ = Formula [Bookmark ] [\#Numeric Picture ] }
A formula is an expression that can contain any combination of numbers, bookmarks that refer to numbers, fields resulting in numbers, and the available operators and functions. The expression can refer to values in a table and values returned by functions..
Operators: In an = (Formula) field, you can use any combination of values and the following mathematical and relational operators.
+ Addition– Subtraction* Multiplication/ Division% Percentage^ Powers and roots= Equal to< Less than< = Less than or equal to> Greater than> = Greater than or equal to< > Not equal to
Functions The = (Formula) field can use values returned by the following functions. Functions with empty parentheses can accept any number of arguments. Arguments must be separated by the list separator defined in the regional settings in Microsoft Windows Control Panel, either a comma (,) or semicolon (;). Arguments can be numbers, formulas, or bookmark names. The functions AVERAGE(), COUNT(), MAX(), MIN(), PRODUCT(), and SUM() can also accept references to table cells as arguments.
ABS(x) Returns the positive value of a number or formula, regardless of its actual positive or negative value.
AND(x,y) Returns the value 1 if the logical expressions x and y are both true, or the value 0 (zero) if either expression is false.
AVERAGE( ) Returns the average of a list of values.
COUNT( ) Returns the number of items in a list.
DEFINED(x) Returns the value 1 (true) if the expression x is valid, or the value 0 (false) if the expression cannot be computed.
FALSE Returns 0 (zero).
INT(x) Returns the numbers to the left of the decimal place in the value or formula x.
MIN( ) Returns the smallest value in a list.
Page 18
MAX( ) Returns the largest value in a list.
MOD(x,y) Returns the remainder that results from dividing the value x by the value y a whole number of times.
NOT(x) Returns the value 0 (zero) (false) if the logical expression x is true, or the value 1 (true) if the expression is false.
OR(x,y) Returns the value 1 (true) if either or both logical expressions x and y are true, or the value 0 (zero) (false) if both expressions are false.
PRODUCT( ) Returns the result of multiplying a list of values. For example, the function { = PRODUCT (1,3,7,9) } returns the value 189.
ROUND(x,y) Returns the value of x rounded to the specified number of decimal places y; x can be either a number or the result of a formula.
SIGN(x) Returns the value 1 if x is a positive value, or the value –1 if x is a negative value.
SUM( ) Returns the sum of a list of values or formulas.
TRUE Returns the value 1.
Example:
{ = 1 + 3 - 1 }
Formula fields can be nested and can use results of other fields as parts. They can be used as a part of conditional fields and bookmarks. For example:
{= ({MERGEFIELD order} + 100)}
{= BOOKMARK1 + BOOKMARK2}
{= {MERGEFIELD FIELD1} + {MERGEFIELD FIELD2}}
You can perform multiple calculations in one EXPRESSION field. The below sample will multiply .825 by the {Mergefield amnt} if the {Mergefield state} is equal to NY otherwise it will multiply {Mergefield amnt} by .725 if it is any other state:
{IF {MERGEFIELD State} = "NY" {=({MERGEFIELD amnt} * .825} {=({Mergefield amnt} * .725)} }
7 Conditional contentNot all content within a Document Template will be relevant to each end Document. Depending on the user’s answers on the Form, you may wish to include some content and exclude other content. This is called ‘conditional content’.
Page 19
Conditional content is included or taken out of a Document Template by the use of the <IF> statement.
The <IF> statement is usually driven by the answer to a Field in a Form. For example, the form may ask the question “Do you have a dog?” [Field: Has_Dog_yn] If the User answers ‘yes’ to this question, then certain content will be included in the Document, otherwise the content will be left out. This would be achieved using the following statements in the Document Template:
7.1 An <IF> statement with a Yes/No field:
«IfStart:1»
We are happy to hear that you have a dog!
«IfEnd:1»
The <IF> statement can be used for most types of Fields, i.e. Yes/No Fields, Choice Fields and Number Fields. Each type of Field is discussed at paragraph 4.
7.2 An <IF> statement with a Choice Field:A Choice Field is a Field that provides the User with a number of options to choose among or between. Some Choice Fields only allow the User to make one choice (e.g. a Radio Button and Drop-Down Lists), while others Choice Fields allow the User to make multiple choices (Checkbox Lists).
«IfStart:1»
This content will be left in the Document if the User selects ‘Choice1’ on the Form, otherwise it will be removed.
«IfEnd:1»
Page 20
Because there are a number of potential answers that the User can select, the statement uses the wildcard symbol of ‘%’ before and after the choice wording. This will enable the statement to work even if the User makes more than one selection in a Choice Field (e.g. in a Checkbox List).
7.3 An <IF> statement with a Choice Field when a choice ‘IS NOT’ made:You can include content within a Document if a User does not choose an option in a Choice Field. This is done using the ‘Not Like’ statement in the mergefield as follows:
«IfStart:2»
This content will be shown if the User does not choose the option ‘Choice1’.
«IfEnd:2»
7.4 An <IF> statement with a Number Field:The <IF> statement can also evaluate a number. For example, you may only wish to include content in a document if the value in a Number Field is greater than a certain value:
«IfStart:2»
This content will be shown if the value of MyNumber_num is 2 or higher, (i.e. greater than 1).
«IfEnd:2»
Page 21
7.5 Insert content if a Field is blank or empty:Sometimes you may only wish to include content in a document if a Field has been left blank, or you may wish to include the content of a Field only if something has been entered into the Field in the Form. Both of these things can be achieved with the <IF> statement, as follows:
Include content if the Field Content_txt has been left blank:
«IfStart:Content1»
This will show up if Content_txt is empty.
«IfEnd:Content1»
Include content if a value has been entered into the Field Content_txt:
«IfStart:Content1»
This will show up if Content_txt has some content – which in this case is: «Content_txt».
«IfEnd:Content1»
7.6 Insert content if a Field is one thing OR another Field is another thing:You can also include multiple criteria for the inclusion or exclusion of conditional content. For example, you can insert content based on one Field being true OR another Field having a certain value:
Page 22
«IfStart:OR1»
This will show up if either Field1_yn is true or Field2_num is greater than 0.
«IfEnd:OR1»
7.7 Insert content 2 or more conditions are met:You can include multiple criteria for the inclusion or exclusion of conditional content. For example, you can insert content based on one Field being a certain value AND another Field being a given choice:
«IfStart:AND1»
This content will be inserted if Field1-num is greater than 0 and Field2_cho includes the selection of ‘Choice’.
«IfEnd:AND1»
7.8 Some common mistakes with conditional contentIf an <IF> statement is not working make sure that the name of the beginning <IfStart> statement and the ending <IfEnd> statement reference the same name, (for example IfStart:AND1 and IfStart:AND1).
Make sure that there are no spaces between the IfStart or IfEnd statement and the reference name.
Page 23
An <IF> statement cannot span across a section break within the Document Template. Furthermore, an <IF> statement cannot ‘cross’ over another <IF> statement – they needs to be completely nested within each other.
8 Conditional Field content – Short-IFsAnother form of conditional content is when certain words are inserted if a condition is true, and alternative words are inserted if a condition is not true. This is performed within a mergefield using the <IF> statement.
The syntax is:
If Expression1 is a string (and contains spaced, use quotes):
{IF "Expression1" Operator "Expression2" "TrueText" "FalseText"}
If Expression1 is a number:
{IF Expression1 Operator Expression2 "TrueText" "FalseText"}
You can use a "?" to replace a character in Expression 2. This only replaced a single character.
You can use "*" to replace a series of characters in Expression 2. NOTE: This can only be used once.
Operators include "=", "<>", "<", ">", "<=", ">="
For example, you may wish to insert one word if a Field is plural, and another word if the Field is singular:
You can also insert multiple words:
And include other Fields in the content that is inserted:
Page 24
In order to create an AND logic with two conditions, you need to use 2 IF conditions as follows:
Syntax: {IF test1 "{IF test2 "TrueResult" "FalseResult"}" "FalseResult"}
In order to create an OR logic between two conditions, you need to use 2 IF conditions as follows:
Syntax: {IF test1 "TrueResult" "{IF test2 "TrueResult" "FalseResult"}"}
8.1 Inserting a checkbox outcome into a DocumentYou can also use an <IF> statement within a mergefield to insert special characters into the Document.
9 MergeTextMergeText is a form of conditional text that merges in particular text depending on the answer to a given field. Mergetext is a extremely powerful way to add dynamic and conditional content to your documents.
There are two types of MergeText: MergeText Values and MergeText Lists.
9.1 MergeText Values on fieldsThe first type of MergeText is text that is part of the field properties. This MergeText Value inserted into the document when the extension '_MText' is added to the field name in the template.
«Type_cho_MText»
The MergeText Value property is the third element of the choice within the field. So for a choice field, the properties of one of the choices may be 'Male|This person is a man|his':
Page 25
The first element of the property 'Male' is the field value. This is stored as data; The second element of the property 'This person is a man' is what is displayed in the
form for the user to select; and The third element of the property 'his' is the MergeText Value. This is what will be
inserted into the document when it is assembled and the field has the extension _MText added to the end.
9.2 MergeText ListsThe second type of MergeText is text that is taken from a separate 'MergeText List' and inserted into the document depending on what option has been selected on the associated field.
A good use of a Mergetext List is when you are referring to someone in a document, and you want to take into account whether they are a male or female. For example, you may say “Mary is able to visit her lamb, so long as she finishes her dinner”. Where as if you were talking about John, you would want to say “John is able to visit his lamb, so long as he finishes his dinner”. By running mergetext of the sex of Mary/John, you can have ZumeSoft insert the relevant content.
The syntax for a MergeText List insert is:
«Type_cho»
The text selected from the MergeText List corresponds with position selected on the choice control. So if the choice control had 3 choices, and the MergeText List had 3 blocks of text, when option 2 is selected on the choice control, text block 2 is inserted from the MergeText List.
You can create MergeText Lists in your forms in the Form Designer.
There are a number of standard MergeText Lists included with all forms, e.g. 'HisHerTheir'.
9.2.1 Using other fields within a MergeText ListYou can include form fields in the content of MergeText Lists. For example:
Page 26
9.2.2 Using one MergeText List within another MergeText ListYou can also reference a MergeText List within another MergeText list.
The syntax for this is:
“MTEXT\(MergetextList, Field)”
You can also include text before and after the MTEXT list, for example:
“your MTEXT\(SalHisHer, Sal_cho)”
A MergeText List that you are referring to within a MergeText List may itself refer to another MergeText List, so you can effectively have multiple layers of MergeText Lists within each other.
10 Multi-row or table dataSometimes a Field needs to contain multiple data. For example, a range of numbers, a list of dates, or a number of lines on an invoice.
In order to record and store this type of data you can use a Field surrounded within a <Table> statement. The <Table> statement enables the User to enter multiple lines of data into the one Field.
Page 27
10.1 The <Table> statementThe <TableStart> and <TableEnd> statements are used to insert multi-row data into a template.
«TableStart:Table1_rpt»
These are words that will be displayed on each line of the document, together with the unique data item itself: «Table_Content_Item».
«TableEnd:Table1_rpt»
10.2 Conditional table contentEach item in the multi-row table date will only be inserted into the document if the condition put in the opening <Table> statement is met:
«TableStart:Table1_rpt»WF:DelEmptyPara
These words and the content of this fields «Table_Content_Item» will only be inserted on this line if Condition_yn is ‘true’.
«TableEnd:Table1_rpt»WF:DelEmptyPara
This will cycle through the table rows and only insert a row for which ‘Condition_yn’ is ‘true’.
Page 28
10.3 Repeats within a MS Word tableYou can use the <Table> statements to populate a table in a Document Template. You need to include the <TableStart> and the <TableEnd> statements within the same Document table row:
«TableStart:Table1_rpt» «Table_Content_Item»
«TableEnd:Table1_rpt»
10.4 Count repeatsIt is often useful to know how many rows of data have been entered into a particular <Table>. This can be determined using the *_Count extension on the Table name Field. The following logic will depend on the number of rows in the table repeat:
«IfStart:REPEAT1»
This content will show up if Repeat_rpt has more than 1 row.
«IfEnd:REPEAT1»
10.5 Accessing a field one level above a repeatWhen you are dealing with repeating data understanding ‘context’ becomes critical. This is because the perspective you are looking from within your template will determine what data you can see.
For example, if you have the name of a person on a form, and have a repeating section under that, you will not simply be able to access the name of the person when using the repeating data in your template.
To access a field value above (or outside) a repeat you preface the field name with the name of the repeat, following by “.”. For example, say you have a field Person_txt that is outside a repeating section called Repeat_rpt. If you can want to insert Person_txt inside the repeat you would use the syntax:
{ MERGEFIELD Repeat_rpt.Person_txt }
11 ZumeForms SwitchesZumeSoft has certain built in WF Switches that can alter the content of a Template Document when the document is assembled. This is usually handy for tidying up the Document after it has been assembled.
Page 29
11.1 WF:DelEmptyParaThe WF:DelEmptyPara Switch will remove a paragraph mark if there is no content in the paragraph. This has the effect of removing empty lines from the finished Document.
In the following example, if one or more of the lines of the address are not present, then there will not be a gap above, below or between the entered lines.
«AddressLine1»WF:DelEmptyPara
«AddressLine2»WF:DelEmptyPara
«AddressLine3»WF:DelEmptyPara
The same technique can be used to remove the empty lines that would otherwise be left from Field statements:
«IfStart:REPEAT1»WF:DelEmptyPara
This content will show up if Repeat_rpt has more than 1 row.
«IfEnd:REPEAT1»WF:DelEmptyPara
It is very important to ensure that there are no spaces between the end of the content and the WF:DelEmptyPara Switch. If there is a space then the paragraph will not be considered ‘empty’ and the blank line (with the space) will be left in the Document after assembly. If you have strange blank lines in your Document, this is probably the reason.
Page 30
11.2 WF:DelRowThe WF:DelRow Switch is similar to the WF:DelEmptyPara Switch, except that it applies to rows in tables. This is best used to remove a row of a table in a Document if certain conditions are met (or not met).
«TableStart:Table1_rpt»
«TableEnd:Table1_rpt»
12 List FormatttingThe <ListFormat> statement will format lists in Documents accordingly to set rules.
In order to implement the <ListFormat> statement three components are required:
First you need an opening <ListFormatStart> statement before the paragraphs. Then you need to include a <ListItem> statement at the end of each paragraph where
you want to include the list formatting, i.e. the “.”, “;” or “; and”, etc. Finally you need to include a closing <ListFormatEnd> statement after the end of the
paragraphs.
For example:
«ListFormatStart:List1»WF:DelEmptyPara
«TableStart:TableList_rpt»WF:DelEmptyPara
«Content_txt»«ListItem:List1»WF:DelEmptyPara
«TableEnd:TableList_rpt»WF:DelEmptyPara
«ListFormatEnd:List1»WF:DelEmptyPara
You can also do ‘in-line’ list formatting:
Page 31
«ListFormatStart:List1»«TableStart:TableList_rpt»«Content_txt»«ListItem:List1»«TableEnd:TableList_rpt»«ListFormatEnd:List1»
The rules currently supported by ZumeSoft are:
13 System User fieldsThe Zumesoft system has a number of internal fields that can be used to insert content into a template by using them within a Mergefield.
In order to access this content you can use the fields listed below. You must put the prefix “User:” in front of each field, i.e. User:NameFirst («User:NameFirst»):
DateCreated UserName (i.e. the username that the User used to create their account. This is often
their email address, but not always) NameFirst NameLast AddressLine1 AddressLine2 AddressPostCode AddressState AddressCountry EMail EmailWork TelephoneHome TelephoneWork TelephoneMobile BillingName BillingAddressLine1 BillingAddressLine2 BillingAddressPostCode BillingAddressState BillingAddressCountry Entity
Page 32
AllowFinalise MonthlyCredit UserIDReferrer ABN EmailNotify1 EmailNotify2 License Title JobTitle CustomSystemFee AddressCO AddressSub EntityAddressCO EntityAddressLine1 EntityAddressLine2 EntityAddressSub EntityAddressPostCode EntityAddressState EntityAddressCountry Fax URL LegalABN LegalEntity HostID GroupName
14 Standard template components
14.1 Person details«Client_Sal_cho»«Client_Name_First_txt» «Client_Name_Middle_txt» «Client_Name_Last_txt»«Client_Suffix_cho»
14.2 Standard address – multi-lineNote: This will only show the country if it is not Australia:
«[ID]_ADDR_CO_TXT»WF:DelEmptyPara
«[ID]_ADDR_FLOOR_TXT»WF:DelEmptyPara
«[ID]_ADDR_1_TXT»WF:DelEmptyPara
«[ID]_ADDR_2_TXT»WF:DelEmptyPara
«[ID]_Addr_Suburb_txt_Mtext»«[ID]_Addr_State_txt»«[ID]_Addr_PC_txt»
WF:DelEmptyPara
Page 33
14.3 Standard address – one line
14.3.1 Standalone address:Note: This will only show the country if it is not Australia:
«[ID]_Addr_Level_txt»«[Id]_Addr_1_Txt»«[Id]_Addr_2_Txt»«[Id]_Addr_Sub_Txt»«[ID]_Addr_State_txt»«[ID]_Addr_PC_txt»
14.3.2 In-line address:
«[ID]_Addr_Level_txt»«[Id]_Addr_1_Txt»«[Id]_Addr_2_Txt»«[Id]_Addr_Sub_Txt»«[ID]_Addr_State_txt»«[ID]_Addr_PC_txt»
Page 34
