Rich Style Doc Template

SKIP AHEAD TO
Reference Input Variables
Conditional Text Display
Looping Text and Dynamic Tables
Dynamic Paragraphs and Numbered Lists
Formatting in the Document Template
Adding Uploaded Images 
Customising your Report File Name

This article outlines how to produce a Checkbox Document output using a Word Document template. 

Document Template Uploads are done with the same block as Document Builder, so it is recommended that you are familiar with Document Builder.

Doc_Gen_Block.png

 

To upload your Word Document template:

  1. Click on your Doc-Gen block
  2. Check the box Use docx template
  3. Upload .docx file

Upload_docx_template.png

 Creating a Word Document template that is compatible with Checkbox is very similar to creating a document in Checkbox's Document Builder, with a few small changes to functionality and syntax.

The syntax requirements for Document Template Upload are detailed below.

 

Reference Input Variables


To automatically add user inputs to your Document, use curly braces similar to those in the Document Builder. For example, {{TXT45}} in the template will be replaced with the value of TXT45 when the Assessment's Document is produced.

Note that the styling of the variable in the Document will reflect the styling of the first bracket in the reference. For example {{TXT45}} will appear as bold text in the Document because the first bracket is bold. The styling of the remainder of the reference will not impact the final styling.

 

Note:

By using a specific syntax, FILE variables can be used to display uploaded images with JPEG or PNG file types in Rich Documents. However, you cannot use standard FILE variables (e.g. {{FILE2}}) in Document Builder or Rich Documents to reference other files (e.g. .docx, .pdf, .xlsx, etc) uploaded earlier, as it is designed only to allow users to download files within the assessment (rather than in an end Document).

To learn more about how FILE variables work, click here under the 'Referencing FILE Variables subheading'.

 

Conditional Text Display


Similar to document rules in the Document Builder, you can design your template to conditionally display sections of text based on user inputs.

To start a conditional section, type {{# expression}}

  • The expression is the condition that needs to be true for the subsequent text to appear

To end a conditional section, type {{/}}

For example:

{{#Account_Balance < 0}} Your account balance is below zero {{/}}

 

If you want to only show a portion of the rich document based on multiple conditions, then you can apply the full range of operators and variables used to configure conditions in the Checkbox studio.

If you only want to display a portion of the text if condition 1 and condition 2 are satisfied, type && between the two conditions.

For example:

{{#Account_Balance < 0 && Account_Name == "James"}} 
Your account balance is below zero and your name is James {{/}}

 Note: In Checkbox, if you would like to check if a variable like 'Account_Name' is equal to something else, you use the double equals ('==') notation displayed above.

 

If you would like to display a message if condition 1 or condition 2 are satisfied, type || between the two conditions.

For example:

{{#Account_Balance < 0 || Account_Balance > 100}}
Your account balance is either below zero or above 100 {{/}}

 

To make more complex requirements for displaying a particular message, string together as many AND or OR statements you deem appropriate in the same way as displayed above.

For example:

{{#(Account_Balance < 0 || Account_Balance > 100) && 
(Account Name == "James")}}
James, your account balance is either below zero or above 100 {{/}}

Note: The brackets ( ) were placed around the first two statements because it indicates that if both of them are false or the Account name is not James, then the message will not display. 

If the brackets were placed in a different area, as shown in the example below, then the meaning would be more like the following:

{{#Account_Balance < 0 || (Account_Balance > 100 && 
Account Name == "James")}}
Either your account balance is below zero or your name is
James and your account balance is above 100 {{/}}


You can also create conditions that will be met if a text variable is not null. That is, if there is any user input for the text input field, the condition will be met.

The syntax for this is as follows:

Format Example
{{#!!TXT#}} display text {{/}} {{#!!TXT12}} display text {{/}}


For example:

{{#!!TXT12}} display any text here {{/}}


Note:
If the text variable name has been changed, please refer to the respective variable name.

  

Looping Text


Similar to Document Loops in the Document Builder, you can create looping sections of text that make reference to a LIST variable in the application.

To start a Loop section, type {{LOOP(List reference)}}

To end a Loop section: {{ENDLOOP(List reference)}}

To access the entries in a list, add a .item postfix to a List reference (List reference.item) (This takes the place of VAL1 from Document Loops).

Without the .item postfix, only the length of a list will be considered by a condition, not the entries within the list. Also note that when referencing a list within a Loop section, a difference list can be referred to than the one used in {{LOOP(List reference)}}.

 

 Basic use of Loops in a template 


Assume LIST12 contains 3 items; apples, oranges, pears

 {{LOOP(LIST12)}} This grocery store stocks {{LIST12.item}}
{{ENDLOOP(LIST12)}}

This will display:

This grocery store stocks apples.

This grocery store stocks oranges.

This grocery store stocks pears.

 

Bulleted and numbered lists

To display a numbered list, using the above example, add the following:

    This grocery store stocks: 
{{LOOP(LIST12)}} 1. {{LIST12.item}} {{ENDLOOP(LIST12)}}

 This will display:

This grocery store stocks:

  1. apples
  2. oranges
  3. pears

When adding a numbered list, use the numbered list functionality in Word.

The same applies for a bulleted list.

 

Multiple List references within a Loop section


Referring to the above example, if the entries for fruits that the grocery store stocked (entries you want to print) were instead stored in LIST11, but you wanted a number of Loop iterations equal to the number of entries in LIST12, write:

 {{LOOP(LIST12)}}
This grocery store stocks:
1. {{LIST11.item}}
{{ENDLOOP(LIST12)}}

If LIST11 again has 3 entries, but LIST12 only has 2, the following will display:

 This grocery store stocks:

  1. apples
  2. oranges

If LIST12 has 3 or more entries, all entries in LIST11 will be displayed.

 

Insert Dynamic table rows in a Rich Style Document


To emulate the App’s dynamic table Inside the document, you can either use conditions or the loop functions. Conditions are typically used this way for one instance of a dynamic table row while loops are used for multiple dynamic table rows.

Dynamic Table Row by Condition Logic Tag

To insert a dynamic row using conditions:

  1. Write an opening logic tag in the first column
  2. Enter the text or reference variables across the columns in the same row
  3. Write a closing logic tag to signify the end of the dynamic row
Column 1 Column 2

{{#LikeDog=="Yes"}}Please specify what breed of dogs you like:

{{DogBreed}}{{/}}


Limitation:
You cannot close logic tags in the MIDDLE of a table cell that is different to the cell with the opening logic tag. For example, the below table will be invalid since in column 2, there are other items after the closing tag {{/}} (bolded).

Column 1 Column 2

{{#LikeDog=="Yes"}}Please specify what breed of dogs you like:

{{DogBreed}}{{/}}{{#DogBreed=="Other"}} – {{Other_DogBreed}}{{/}}

 

Dynamic Table Row by LOOP

To emulate the App’s dynamic table Inside the document with multiple rows using loops, you must:

  1. Create a regular table in inside your Word document

  2. Insert a LOOP function for the dynamic with the appropriate syntax. See syntax below

  3. Insert the variables from the dynamic row in the TABLE block using double curly brackets with a “.item” suffix (e.g. {{TBL14_D3.item}})

 

Loop function syntax:

To enable a dynamic row in the table inside the document, you must use a LOOP function for the row under the header of the table. For a LOOP function to work, a LIST variable must be referenced at the start (i.e. LOOP) and end (i.e. ENDLOOP) of the function. All table variables in the dynamic row must include the suffix “.item” (e.g. {{TBL14_B2.item}}). Learn more about table variables.

i.e.

Column 1 Column 2 Column 3 Column 4
{{LOOP(LIST#)}}{{insert table variable.item}} {{insert table variable.item}} {{insert table variable.item}} {{insert table variable.item}}{{ENDLOOP(LIST#)}}

 

Example of Dynamic table rows:

For example, in the case of the screenshot below, we have referenced a dynamic list (LIST10) inside cell A2 of TABLE block (TBL14), therefore the syntax for the dynamic table row is LOOP(TBL14_A2) and ENDLOOP(TBL14_A2). Any variables referenced within the loop (i.e. the dynamic row - in this case, row 2 of TBL14) must add the suffix “.item” (e.g. {{TBL14_B2.item}}). 


TBL14 structure (in App):

Quick_Fixes_WIki_-_Google_Docs_2020-09-11_11-25-57.png

Rich Document Implementation:

Budgeting_Report_Example_Template_2_2020-09-11_11-26-34.png

 

 

Dynamic Paragraphs and Numbered Lists


If your document has a numbered list of paragraphs that you want to make conditional based on the answers provided during an assessment, templates can handle this too.

Taking the grocery store example from above, let's ask for what the grocery store stocks in a list of checkboxes, so that:

 CBX1 == "TRUE" means the store has apples

 CBX2 == "TRUE" means the store has oranges

 CBX3 == "TRUE" means the store has pears

You can present this in the document template as:

This grocery store stocks:
{{#CBX1 == "TRUE"}}
1. apples {{/}}
{{#CBX2 == "TRUE"}}
2. oranges {{/}}
{{#CBX3 == "TRUE"}}
3. pears {{/}}

 

During the assessment, if the user only checks CBX 1 and CBX 3, the Document will display:

This grocery store stocks:

  1. apples
  2. pears

As you can see, while 'pears' is the third entry in your template, it appears as the second entry on your Document as the condition for oranges wasn't met.

 

Note: To ensure the word document retains the correct order in the numbered list, after you type:

{{#CBX1 == "TRUE"}}
1. apples {{/}}

 

Press Shift + Enter. This will add a line under '1.' where you can then type the next condition. After the next condition, simply press Enter and '2.' will appear.

 

Formatting in the Document Template


Variables with Field Formatting do not automatically carry over this formatting when referenced in a document template. To reference a variable, you must include the text :formatted inside the variable reference.

For Example, if you've set-up NUM15 to have the $ prefix, and the user inputs 20.

  • {{NUM15}} will return 20 in the document output.
  • {{NUM15:formatted}} will return $20 the document output.

This applies to all formatting - dates, percentages, decimals, prefixes etc.

 

Adding Uploaded Images


Images that were uploaded during an assessment through the File Upload field in a Form page can be included in Document templates.

Limitations: 

  1. Supported image file types are JPEG and PNG
  2. Only up to 50 images can be uploaded in the File Upload field at one time (For example: To upload 100 images, you will need to upload the first 50 images before continuing to upload the remaining 50 images)

 

To add an image into your Document, use the following syntax:

Note: Each line of text must be separated with spaces as shown below.

INCORRECT Formatting:

{{#FILE1}}
{{%image}}
{{/FILE1}}

CORRECT Formatting:

{{#FILE1}}

{{%image}}

{{/FILE1}}

Where 'FILE1' is the variable name of the File Upload field and '%image' is the fixed variable where all uploaded images will be appear in the document. This syntax will allow the user to add the image into the Document at the size that it was uploaded. Should the size of the image exceed the width of the document the image will be automatically resized to fit the width of the page.

 

Restricting image size

To restrict the size of the image you can use either of the following two methods.

1. Restricting the pixel width of the image.

{{#FILE1}}

{{%image | size:100}}

{{/FILE1}}

The above restricts the image to a width of 100 pixels. The image will retain the original ratio by adjusting the pixel height automatically.

2. Restricting both the pixel width and pixel height of the image.

{{#FILE1}}

{{%image | size:200:300}}

{{/FILE1}}

The above restricts the image to a pixel width of 200 pixels and pixel height of 300. This will overwrite the original image ratio.

Note: Image default alignment format will be ‘Center’

 

 

Customise your Report File Name

  1. In Studio, click onto your ‘Doc Gen’ block.
  2. On the right panel under ‘Settings’, enter the Report file name you want the document to be generated with.

Note: We currently only support static text and variables including text, number, date and meta variables from FORM, TABLE and COMP Table blocks.

V1.15_Release_Notes___Email___Wiki_-_Google_Docs_2020-05-07_08-33-47.png