Doc Merge Appendix

Overview

Doc Merge is a powerful document-generation tool that allows you to pull data from Sugar® records into professional-quality and highly customized documents. This supplemental resource can be used as a reference to understand the different attributes, collections, directives, and more available when building templates, which will help you create specialized documents that suit your organization's needs.

Please review the Doc Merge page for generalized information on building templates. Additionally, refer to the Sample Doc Merge Templates article for document examples.

Topics

This documentation is organized into the following sections:

• Doc Merge Terminology
• Fields
• Collections
• Conditions
• Directives

Doc Merge Terminology

This document uses language specific to Doc Merge. Please review the definitions below as they will help you understand the examples provided.

• Merge Code: A tag you can insert into a document template that will generate content in the final, merged document according to your specifications. For example, a field merge code is used to display the value of a field on the target record. The following are the types of merge codes:
  • Field: Insert the value of a field from the target record into the document, such as the name or contact details of an account.
  • Collection: Iterate over a list of records, allowing you to display field values from those records in the document, for example in a list or table of sales data. These may sometimes also be called "loops".
  • Condition: Print different values in the document based on the state of a condition. For example, you might print a measurement in one unit if the account's country is USA or a different unit if it is Canada.
  • Directive: Insert a formatted object into the document, such as a table, a list, the current merge date, or the output of a Sugar Logic calculation. 
• Attribute: A setting you can specify on various merge codes to control specific details of what they output. For example, a collection has attributes to control the sort order of the items in the collection and the maximum number of records to display.

Please note that attributes must be written without any blank spaces within the syntax (e.g., max_num='5'). Having spaces in an attribute's syntax will lead to the template not being processed. Additionally, Doc Merge only supports straight quotes ' inside of attributes. Do not use ` or ‟. Many modern devices use Smart Quotes, a form of autocorrect, which turns quotes toward the code or comment. You may turn this off or use the Unicode character U+0027 to ensure the quote is straight.

Fields

Field merge codes insert the value of a module's field into the document. For example, you may pull an account's address directly into a letterhead. This can be used to create personalized and robust contracts, quotes, and other documents for your business needs. Additionally, field-level attributes allow customization that can be used in all types of fields. 

While merge code examples are presented with stock fields in the below sections, any custom field, relationship, or module may be used with merge codes. You can use the Template Assistant to assist with gathering these items, or you may also use Studio to find the names of custom fields and module relationships.

Field Types

Relationships

Relationship field types allow you to pull data from a related module without creating a collection (loop). 

In this example, the assigned_user_name field is appended to gather further data from the Users module:

Relate Fields

Relate fields are not relationships, and therefore cannot be merged as in the above example.  Instead, they are fields and can be merged from the target module using the field's name: {#contacts}{name}{relate_field_c}{/contacts}.

Multiselect Fields

Multiselect fields are fields within Sugar that can have multiple options chosen. These results can be formatted in Doc Merge in a number of different ways.

Email Fields

Since records can have more than one email address, you must either specify which email address you are referring to or iterate over them using a collection. Use the following two methods to output email addresses: 

• Use {email1},{email2},{email3} if you want to generate specific email addresses
• Use loops in order to generate all email addresses for a record: {#email_addresses}{email}{/email_addresses} 

Date Fields

Date fields may also be pulled in via Doc Merge and can be formatted to suit your document's needs.

Note: You may also use any other format found here: http://momentjs.com

Datetime Fields

Datetime fields, not to be confused with date fields, may be pulled in and formatted within merged documents.

Merged documents display time using the browser's time zone, as opposed to the time zone set on the operating system. You can use the moment() function in your browser's development tools to get the browser's local time zone.

Checkbox Fields

Checkbox fields may be brought into your document and formatted as a word, number, or symbol.

Image Fields

Doc Merge supports the following image file types: JPEG, GIF, PNG, BMP.

Example Merge Syntax	Merge Results
{image_c}

TinyMCEFieldType Fields

The following formats used inside TinyMCE fields are supported:

• Bold
• Italic
• Underline
• Font color
• Highlight color
• Font size
• Lists: bullets and numbers

The syntax for TinyMCE fields is {TinyMCE_fieldname format='docx'}.

URL Fields

A URL field can be converted into a hyperlink with your choice of text or a clickable URL:

Field Attributes

An attribute is a setting you can specify on various merge codes to control specific details of what they output. There are several different attributes, some that apply only to certain field types, such as {checkbox_name format='boolean'}, while others apply to many different field types, such as {case=''} or {pad=''}. For example, a collection has attributes to control the sort order of the items in the collection and the maximum number of records to display. The following field attributes in this section relate to multiple types of fields.

Case and Capitalization

The below table shows some examples of how case and capitalization may be formatted. This example is gathering data from the "Department" field in the Users module. The initial value in Sugar when this merge took place was "sales and SUPPORT".

Note: Capitalize set to 'false' will have no effect on the string. capitalize is best used for scenarios where you want to assure yourself that the string will start with an uppercase or lowercase letter.

Padding

Padding a field adds a predefined number of leading spaces. This can be useful for formatting fields in a document where you want all fields to be aligned a certain way. If the returned field value is "TEST" and the pad value is 10, the resulting string will be "      TEST" (i.e., six spaces will be added so the total number of characters in the merge result becomes 10). If the pad number defined is less than the length of the field value being merged, the merge results will not be padded.

In this example, the email address being merged (test.example@email.com) is 22 characters in length. 

Note: The pad attribute cannot be used with sort, format, case, or capitalize attributes. This is because padding text gets applied to the code as opposed to the field values. 

Pre-Formatted Fields

Sugar has some fields that are already formatted. For these fields, only the field name needs to be placed within the curly braces.

For stock date/time fields, the default formatting is {MM-DD-YYY h:mm a}.

For currency, the format is determined using the user's Preferred Currency setting. The below examples use the Opportunities module and the user's preferred currency is USD $.

Barcodes

Doc Merge has the ability to format fields as barcodes using the following syntax: {field_name format='barcode'}. 

Example Merge Syntax	Merge Results
{field_name format='barcode' barcode-format='EAN13'}
{field_name format='barcode' barcode-format='CODE39'}
{field_name format='barcode' barcode-width='2' }
{field_name format='barcode' barcode-height='150' }
{field_name format='barcode' barcode-height='25' }
{field_name format='barcode' barcode-text='Hi!' }
{field_name format='barcode' barcode-font-options='bold/italic/bold italic' }
{field_name format='barcode' barcode-textAlign='left' }
{field_name format='barcode' barcode-textPosition='top' }
{field_name format='barcode' barcode-textMargin='25' }
{field_name format='barcode' barcode-fontSize='40'}
{field_name format='barcode' barcode-background='#ccffff' }
{field_name format='barcode' barcode-lineColor='#990000' }
{field_name format='barcode' barcode-margin='30' barcode-background='#dddddd'}
{field_name format='barcode' barcode-marginTop='30' barcode-background='#dddddd'} {field_name format='barcode' barcode-marginLeft='30' barcode-background='#dddddd'}

Additional barcode formats

• CODE128 - default
• CODE39
• EAN13, EAN8, EAN5, EAN2
• ITF, ITF-14
• MSI, MSI10, MSI11, MSI1010, MSI1110
• Pharmacode
• Codabar

For further information on barcode formatting, please reference the JsBarcode Guide.

Collections

Collections loop through a list of records, allowing you to display field values from those records in the document, for example in a list or table of sales data. Information merged into a document is not limited to a specific module record's fields. You can extract information from relationships by using loops:

• {#contacts}: opening merge code for Contacts loop
• {/contacts}: closing merge code for Contacts loop

Stock module relationships are relatively straightforward. If you want to get information from a contact's opportunities, you would use {opportunities} in a template that targets the Contacts module. If you do not know the relationship's name, it can be determined in Admin > Studio > {Module Name} > Relationships. If there are multiple relationships for the same module, the relationship name can also be determined from the data-subpanel-link attribute when inspecting an element using the browser's development tools (F12 in most browsers):

Note: You can only merge up to 40 records in a collection. 

Example

This example will create a list of three contact records ordered by first name in descending order. Each record will have specific values for each contact displayed.

        {#contacts sort='first_name:desc' max_num='3'}
   {salutation} {first_name} {last_name}
   {title}
   {email1}
{/contacts}

Results

Portia Leatherman
IT Developer
kid69@example.name

Mr. Orlando Bou
Senior Product Manager
im.kid@example.net

Marva Rodes
Director Sales
qa.section@example.co.uk

Inner Collections

An inner collection is another collection generated inside of a parent collection. The syntax is the same:

        {#parent_collection}
{parent_collection_field}
   {#child_collection}
       {child_collection_field}
   {/child_collection}
{/parent_collection}

Example

This template will generate all of an account's opportunities and all related contacts for each opportunity. Doc Merge can have as many inner collections as needed.

        Account's name: {name}
Opportunities:
{#opportunities}{name}
  {#contacts}
{first_name} {last_name}
  {/contacts}
{/opportunities}

Results

Account's name: T-Squared Techs

Opportunities:

T-Squared Techs - 175 Units

     Love Abelson

T-Squared Techs - 207 Units

     Justa Montesino

     Guadalupe Schuessler

Conditions

Conditions allow users to print different values in the document based on the state of a condition. This is accomplished by using the if and else merge tags codes, in combination with any conditional operator used in JavaScript. You may find more information on JavaScript conditional operators at w3schools.

Example

{if amount>5000}
The amount is greater than $5000
{elseif amount<=5000}
The amount is less than or equal to $5000
{endif}

Results

This example uses an opportunity with a likely amount of $11,903.70.
Output: The amount is > $5000

Example

{if do_not_call==0} 
{phone_mobile}
{endif}

Results

This example uses a contact that does not have "Do Not Call" checked and therefore can have their phone number displayed in the merged document.

Output: (959) 260-3119 

Example

This example will show the dp_business_purpose field in the Contacts module if the business purpose contains the word "Marketing". If you do not see this field in your contact's record view, you may need to add it to the layout in Studio.

{if (dp_business_purpose.filter(item=>item.includes("Marketing")).length>0)}
{dp_business_purpose}
{else}
NONE
{endif}

Results

In this example, the dp_business_purpose does include the word "Marketing".

Output: Marketing Communications by company 

Conditions Inside a Table

When used in tables, conditionals can make an entire row's visibility dependent on if the condition is met. To delete the entire row based on a specific condition, place the {if $condition} tag in the row's first table cell and the {endif} in the last table cell of the current row. 

If you do not want the entire row deleted if the condition is met, do not place the {if} in the first table cell. Additionally, if you do not want this, do not place the {endif} in the last table cell. Having one of these criteria will cause Doc Merge to delete the row.

Example

In this example, if the contact has "Do Not Call" unchecked, they will appear in the table so that only contacts that should be called will be listed: 

Results

Directives

Directives insert a formatted object into the document, such as a table, a list, the current date, or the output of a Sugar Logic calculation. They can also change the appearance or behavior of a component.

Directives, like other merge codes, are declared inside curly braces but directives are also preceded by an exclamation point: {!directive_name} 

Note: Directives only work for Word and PDF merge. Excel merge is not supported.

table

The {!table} directive inserts a table in the generated document. 

Attributes

• header-color: Any HTML color hex value
• header:  Column names for the table, separated by commas
• columns: Sugar fields you want to insert into the table, separated by commas
• bind: Context for the directive; in this example, this is the module you are retrieving data from 
• sort: Field to sort the table by and the direction of the sort order (i.e., sort='name:asc' or sort='name:desc')
• max_num: Maximum number of records to retrieve from the collection

Note: Since the lists of values in the columns and header attributes refer to the same information (i.e., they represent the data and its display label, respectively), they must both be listed in the same order If there is a mismatch of data, double-check to ensure that the columns match the headers. 

Example

{!table header-color='#ff00ff' header='Name,Primary,Email' columns='name,primary_address_city,email1' bind='#contacts' sort='name:asc' max_num='3'}

Results

table_header

The {!table_header} directive can remove the table header if there is no data in the table. 

Attributes

• hide_no_data: A boolean field to remove the table's header if there is no data in the table. The possible values are 'true' or 'false'. A value set to true will hide the table row if it has no data. False will have no effect on the table's row.
• bind: The module you are retrieving data from

Example

Results

As the criteria for the hide_no_data were fulfilled, the table is not rendered in the generated document.

list

The {!list} directive is for quickly creating numbered lists of related module data. This is similar to collections but is formatted with a number for each related record.

Attributes

• column: The Sugar fields you want to insert into the list
• bind: The module you are retrieving data from
• sort: The field to sort the table by and the direction of the sort order (i.e., sort='name:asc' or sort='name:desc')
• max_num: The maximum number of records to retrieve from the collection

Example

{!list bind='#contacts' columns='name,email1' sort='name:asc' max_num='3'}

Results

1. Piedad Chaffin
2. info28@example.it

1. Piedad Fleagle
2. hr92@example.info

1. Horacio Paulhus
2. section.dev@example.tv

date

The {!date} directive inserts the current date in the merged document.

Attributes

• format: Any datetime format. The default is MM-DD-YYYY, h:mm.

Example

{!date}

Results

08-29-2022, 4:53

formula

Sugar Logic functions may be inserted into your document by using calculated fields. To use calculated fields in Doc Merge, you need to input the formula directive {!formula ...}

Attributes

• value: Any Sugar Logic formula
• format: Any Sugar field type, such as currency or decimal

Example

{!formula value='concat($name, ": ",$quote_stage)} - TEST DOCUMENT

Results

3 Year Service for Smallville Resources Inc: Draft - TEST DOCUMENT