Placeholders - Best Practices

Placeholders are used extensively by SmartIQ and any document being automated by SmartIQ will usually have at least one. In some cases, there may be thousands of placeholders. As the number of placeholders in your document increases, it becomes more critical to follow a naming convention to make it easier to:

find placeholders in Design, and
work out the purpose of the placeholders without needing to jump back to the document.

If you plan and follow a convention right from the beginning, it becomes easier to manage your documents even if they grow larger than they start out.

SmartIQ supports two types of placeholders, Tag placeholders (e.g. {{field}}) and Microsoft Word bookmark placeholder.

Tag placeholders are regarded as the best practice technique within the SmartIQ tool, for reasons such as

Tag placeholders can be used across all document formats such as Word, PowerPoint and XML.
A single Tag name can be used multiple times throughout a document whereas bookmarks can be used once. (E.G. FirstName_01, FirstName_02, etc.) Tag placeholders have clear start and end points whereas multiple bookmarks can appear stacked upon one another or in rare circumstances not viewable at all.
Tag names are always visible in a document, no need to open a separate dialog.
It is possible to distinguish between Tag section and insertion placeholders over the bookmark equivalent, making selections easier in Design.
Tag placeholders preserve the look of a document whereas bookmarks can appear bare, for example, an empty address block.
Tag names are more flexible than bookmarks (the Microsoft Word bookmarking tool does not allow the use of spaces or any special characters besides the ‘_’ character. Also, bookmarks in Word allow a maximum of 40 characters).
Bookmarks in Microsoft Word are not turned on by default and need to be manually enabled by the user.

Bookmarks are still supported but not considered a best practice design technique.

HTML-formatted content can only be inserted using a placeholder from a Rich Text question type, the use of a label or standard text box will cause the HTML tags to be displayed as inserted content. HTML-formatted content does not work for insertion into placeholders in PDF documents.

Tag Placeholder Name Layout

While tags are not grouped into categories, you can apply a meaningful name layout that helps group related tags together. Look at the complexity of the document and determine whether you need to group by one, two or more ‘levels’.

For example, for a simple letter style document, you may wish to use a single ‘level’ of grouping based on the position of the tag placeholder in the document.

**It would look like this:

{{AddressBlock_AddressLine1}}

In a more complex document, such as a contract, you may wish to add additional levels of grouping.

For example:

{{MainContract_ScheduleB_Vendor_Name}}

Tag Placeholder Text

Insertion placeholders are used to mark where data or content is to be inserted in the generated document, while selection placeholders span an area of the document. For examples see How to use {{Tag}} Placeholders

While selection placeholders span actual document content, insertion placeholders have their ‘default’ content replaced when SmartIQ generates a document unless the target data is null, and in that case, the tag placeholder is removed from the document and replaced by empty text. So, basically, the technique is to put the tag name in the document where it should be replaced with content provided by the form,

For example:

Gap and Repeat Placeholders

All placeholders that are to be used only as ‘gap placeholders should end with the word ‘_GAP’. Similarly, all placeholders used to control repeating document areas should end with the word ‘_RPT’.

For example: