Page tree

Troubleshooting Document Templates

As you create and test your document templates, formerly called print templates, use these suggestions to help resolve problems. Most of these solutions apply to document templates with the .docx or PDF file type.

Syntax Errors

Check for these common syntax issues:

  • Parentheses and brackets. Make sure each one is part of a pair, with one opening and one closing the phrase. If you're working with many nested sets of parentheses or brackets, you can copy and paste the text into an HTML editor like Notepad++. These editors highlight the other half of a pair as you move your cursor, so it's easier to tell when a pair is unfinished.
  • Smart quotes (“”). Make sure only plain quotes ("") are used inside formulas. Formulas won't work correctly with smart quotes.

    To disable automatic smart quote formatting, go to File > Options, open the Proofing section, click AutoCorrect Options, go to the AutoFormat tab, and clear the "Straight quotes" with "smart quotes" checkbox.

  • Formula question marks. Question marks are sometimes automatically styled or formatted differently by Word's autocorrect feature. If a formula containing a question mark isn't working, especially ternary formulas, delete and re-enter the question mark character, and use the Word tool to clear formatting on the formula.
  • Formula page breaks. Check each page break to make sure formulas aren't spilling across the break. Formulas broken between pages do not work correctly. If you have a formula near the end of the page, and you aren't sure whether it breaks across the page during testing, you can follow the steps in the Broken Paragraphs section below to force the formula to stay together.
  • Formulas with hidden formatting. For troublesome formulas, especially $startif, $formula, and $field_from_another_table, cut the text and then paste it back in place using Paste as Plain Text (Ctrl+Shift+V).
  • Nested $startif() commands. If the page has a $startif() call inside another $startif(), either on purpose or due to missing parentheses, they won't work correctly.
  • Microsoft Word-formatted clauses in a clause library used inside a $startif() function. If you need to use this combination, create a new global variable named print_template_preprocess_startifs and set it to Yes. This eliminates some formatting issues that can occur during processing.

  • Formula validity. Test your formulas to make sure they work as expected. If you're using a formula for the first time, try testing it with simpler inputs, or test your inputs one at a time.
  • Reenter the field. If you can't identify the problem, try deleting and retyping the field name, rather than copying and pasting. Pasting can include formatting and field codes behind the scenes that sometimes cause problems.
  • Enforce formatting. Make sure the document has consistent formatting and font.

You can also try copying and pasting the entire document into a new Word document to remove ghost formatting.

Broken Paragraphs

There are often sections of document templates that need to stay together. For example, you might want to keep all signature lines together on the same page, so that if the preceding text gets too long, the entire signature section jumps to the next page together. You can make sure sections of the template stay together on the same page.

  1. Highlight the entire section that you need to keep together.
  2. Right-click the selection and click Paragraph.
  3. In the Paragraph window, click the Line and Page Breaks tab.
  4. Select the Keep with next and Keep lines together checkboxes.
  5. Click OK.

Now, the selected paragraphs will always stay together as a whole.

Tables

Refer to Embedding Tables and Fields from Tables for information about including tables. If you're building a complex table, here are some formatting tips for working with tables in Word:

  • To move an individual cell outside the alignment of its neighbors, double-click the cell before you drag its borders.
  • If the ruler is enabled (View ribbon > Ruler checkbox), hold Alt while dragging a border to show the table measurements on the ruler. This makes it easier to center and distribute cells evenly.
  • Tables tend to change shape when you enter long field names, or when the field contents is longer than the field name. To prevent this, right-click the table and select Table Properties. Click Options at the bottom and clear the Automatically resize to fit contents checkbox.

Styles

Make sure to use the Format Painter tool to apply a consistent style to your document template. In particular, use the Format Painter to apply a consistent style to formulas, starting at the $. For example, if you have a $startif formula with an $endif, you should highlight everything from the first $ to the final f in $endif.

If the document template's final output has style problems, but not the original document template, check the style applied to the text inserted to replace formulas and variables. If the style is different than the rest of the document, you might need to modify that style to make it match the style used in the rest of the text, or apply that style to the text in the original document template. For example, inserting text from an HTML field is often automatically set to the Normal (Web) style in Microsoft Word, while the document template body is usually written in the Normal style. Setting the document template body to Normal (Web) or setting Normal (Web) to the same formatting as Normal can fix this issue.

For best results, store clauses as Microsoft Word files and use the Document Template option to prioritize the template's formatting, instead of Use Global Settings or Field. For complex clauses, or clauses that contain images or Word comments, set the specific clause to use AltChunk using the customaltchunk=true parameter. If you need a single clause to both use automatic numbering and include an image, the best method is to split the clause into two parts, so that the numbering can be handled using the document template formatting and the image can be handled using AltChunk.

If the text or list style in the final product still doesn't match the style in the document template, you might need to review the style preference settings for your system, the specific document template, and potentially the individual clause being inserted.

Troubleshooting Styles

First, if the issue comes from inserting a clause, and the clause is stored in a Microsoft Word file rather than an HTML text field, review the text of the document template to locate the variable pointing to that clause text.

  • If it includes the customaltchunk=true parameter, that means the clause is rendered using AltChunk, a feature of Word that preserves the formatting in the clause file rather than converting it to match the template's formatting. AltChunk is necessary if you want to include images, or if the clause is very complex, but it is not compatible with automatic list numbering at the template level. In the template, look for this syntax, and try adding or removing that parameter: $field_from_other_table(clause,161,clause_ms_word_file, customaltchunk=true)
  • You might find that the variable includes use_clause_word_file_num_style=true instead of customaltchunk=true. This retains the list numbering style and order used in the clause Word file, rather than matching the style and order in the document template file. If this is the variable causing issues, try adding or removing the parameter and testing again.

Next, edit the Word/PDF template itself and check the style preferences drop-down setting at the bottom. This controls the style preference for the whole document template.

  • Use Global Settings. Follows the settings in the global variables to determine how to format the contents of the selected field.

  • Document Template. Applies the document template styles to any inserted fields. If a clause contains a bulleted or numbered list, that list is converted to the styles in the document template. This option does not support inserting images from clauses.

  • Field. Uses Microsoft Word's AltChunk paradigm to embed the field's contents with the field's original styles applied. This option does not support automatic numbering.

Finally, if the lower-level settings weren't the problem, check the global variable settings. Log in as an administrator and go to Setup > System > Manage Global Variables.

Remember that any change to global variable settings affects all document templates in the system, not just the one you're troubleshooting.

  • Locate the "Style preference for paragraphs in the output of a document template" global variable. Set this variable to printtemplate to use the style in the document template, or set it to field to use the style coded in the field.
    • If you set this variable to printtemplate and you still see problems with styling, check that all the styles used in the document template have the same font and font size. This includes both the problem text and the Microsoft Word style definitions, which you can access by right-clicking the active Style and clicking Modify.

      When this variable is set to printtemplate, the document template still respects use of bold, italics, and underlining in the field content. If you need to override that behavior, go to the Customized Variables tab and select New > Choice Constant. Create a new global variable named print_template_pref_useRunRpr and set its value to No.

    • If you set this variable to field, the formatted contents of an HTML field is retained in the final product. This is generally only used when users copy and paste formatted content from another program like Word directly into the field. If you use this setting, test your document templates thoroughly because Word doesn't recognize all HTML constructs, even if they are correct in HTML.

  • Locate the "Use AltChunk while running a Generate Document Action" global variable. Set it to No to use the bullet and numbering lists formatted by Microsoft Word, or set it to Yes to ignore Word's automatic list functions and embed field content exactly as-is. In most cases, you want to set this variable to No, which allows usage of automatic numbering in document templates.

If you need to include bookmarks in the final product of a Microsoft Word template, you can configure the system to preserve bookmarks from document templates. To do so, go to the Customized Variables tab and select New > Choice Constant. Create a new global variable named print_template_remove_bookmark and set it to No. This setting applies only to Word document templates, not PDF or HTML formats.