Introduction
S-Docs provides many advanced features for merging data into your S-Doc Template. In most cases described in this document, they require editing of the template source code, which can be easily accessed by clicking on the Source button on the S-Docs Template Editor page.
The template source is based on HTML with specific tags that indicate the S-Docs engine will apply specific mergers or functions.
Merge Field Functions
You can apply multiple functions to merge field data by adding a space and a specific attribute (function) to the end of the field name, like the following:
Single Attribute: {{!Object.Field attribute="value"}} Multiple Attributes: {{!Object.Field attribute1="value1" attribute2="value2" attribute3="value3"}}
For example, {{!opportunity.amount}} will return an unformatted numeric value as it is stored in the Salesforce database; adding {{!opportunity.amount format-number="#,###.##"}} will return the same value, but formatted to include commas and two decimal places.
Please take note of the following:
- All attributes require a space between the merge field name and the attribute.
- When using merge fields within other tags, you may need to escape the HTML in order for the merge to happen properly.
- Be careful when using the Graphical UI editor to change the appearance of the merge field tag. Care must be taken that styling changes do not interject the merged field syntax. E.g. {{!Opportunity.<style= You may need to click on Source to validate that merged fields do not contain any characters.
Rich Text in Merge Fields
S-Docs will interpret HTML code* in a Rich Text merge field (links, text styling and formatting) when the field is surrounded by 3 sets of curly braces instead of 2:
Numbered list: {{{!Object.Ordered_List__c}}}
* Images in Rich Text fields are only supported in PDF and DOCX format. For more, see the Dynamic Images article
Merge Field Attributes
Attribute Name | Usage & Examples | Notes |
---|---|---|
Format-Number | The format-number attribute allows you to custom-format the way numbers are merged into your documents. Only the following EXACT patterns/values are supported for a number format:
Syntax: format-number=" " #,###.## (Typical Currency with cents) #,### (Comma delimited whole number) #.### (EU formatting) #.###,## {{!Opportunity.amount format-number="#,###.##"}} 43222300.8 ➤ 4,222,300.80 {{!Opportunity.amount format-number="#,###"}} 43222300.8 ➤ 4,222,301 {{!Opportunity.amount format-number="#.###"}} 43222300.8 ➤ 4.222.301 |
|
Format-Date | The format-date attribute allows Salesforce date and datetime fields to be formatted into any valid java pattern.
Syntax: format-date=" " {{!opportunity.createdDate format-date="MM/dd/yyyy"}} 2018-10-28 ➤ 04/04/2017 {{!opportunity.createdDate format-date="MMMMM"}} 2018-10-28 ➤ October {{!opportunity.datetime__c format-date="MM/dd/yy hh:mm:ss TZ:America/New_York"}} 2018-10-28 ➤ 10/28/2018 12:56:32 EST |
|
Checkbox | The checkbox attribute allows you to map checked/unchecked checkbox images to boolean fields.
Syntax: {{!opportunity.checkbox__c checkbox="true"}} Displays a checkbox with a dotted white border; includes a black checkmark if checked. {{!opportunity.checkbox__c checkbox="black"}} Displays a checkbox with a solid black border; fills in with black and includes a white checkmark if checked. {{!opportunity.checkbox__c checkbox="radio"}} Displays a radio button. |
|
MICR | The MICR attribute outputs text in MICR E-13B font (Magnetic Ink Character Recognition), which is used for banking and more specifically for generating checks.
Syntax: {{!Check__c.RoutingNumber__c MICR="11"}} To adjust spacing between MICR characters: {{!Opportunity.Description MICR="[FONTSIZE (REQUIRED)],[SPACING (OPTIONAL)]"}} {{!Opportunity.Description MICR="20,5"}}
|
|
CR | The CR attribute (Character Recognition) allows the user to choose to output text in OCR-A or OCR-B font (Optical Character Recognition), which is used for generating checks and other number strings that need to be read by computers without requiring special toner for printing.
Syntax: {{!Opportunity.Description CR="[OCR-A/OCR-B],[FONT SIZE (REQUIRED),[SPACING (OPTIONAL)]"}} Example: {{!Opportunity.Description CR="OCR-B,20,5"}}
|
|
ToUpperCase | The ToUpperCase attribute transforms data to all uppercase characters.
Syntax: {{!contact.billingStreet ToUpperCase="true"}} 123 Main Street, Apt 3 ➤ 123 MAIN ST, APT 3 |
|
ToLowerCase | The ToLowerCase attribute transforms data to all lowercase characters.
Syntax: {{!contact.billingStreet ToLowerCase="true"}} 123 MAIN ST, APT 3 ➤ 123 main street, apt 3 |
|
Right to Left (RTL) | The RTL attribute reverses the character string in the output. This is useful for RTL languages like Hebrew when generating to a PDF.
Syntax: {{!account.greeting__c RTL="true"}} שלום➤ םולש
|
<rtl>reverse</rtl>
|
Translate | The translate attribute uses Salesforce Translation Workbench feature to return the picklist value based on the users locale/language settings
Syntax: {{!product2.color translate="true"}} BLUE ➤ BLEU |
Translate can be used only on picklist fields, but can be used on all field labels.
Click here to learn more.
<!--{{!
|
replaceAll | The replaceAll attribute allows for replacing values with other values. This attribute matches against (and replaces) all substring appearances of the specified string.
Syntax: {{!Opportunity.Name replaceAll="ReplaceThis1,ReplaceWithThis1,ReplaceThis2,ReplaceWithThis2"}} |
|
Encrypt | The encrypt attribute allows for displaying fields with classic encryption set as encrypted in the generated document.
Syntax: {{!Opportunity.EncryptedField__c encrypt="true"}} |
|
Display | The Display attribute will render picklist field values as the field value (the value shown to users on records) instead of field API value. By default, S-Docs renders the field value API name.
Syntax: {{!Opportunity.PicklistField__c Display="true"}} |
|
MSNL | The msnl attribute will replace the semicolons between values from a multi-select picklist with new lines.
Syntax: {{!Opportunity.Multi_Select_Picklist_Field__c msnl="true"}} |
|
breakeverynchars | The breakeverynchars attribute will insert a space after the character number that you specify to allow line breaks
Syntax: {{!Opportunity.Long_Field__c breakeverynchars="10"}} supercalifragilisticexpialidocious ➤ supercalif ragilistic expialidoc ious |
white-space: normal !important; |
toCells | The toCells attribute will break a field value into single-letter cells. This attribute can only be used on merge fields within <td> tags. It is written in the following syntax:
Syntax: {{!Object.Field toCells="Number of Cells to Generate,CSS class to apply to table cells"}} Example: {{!Opportunity.Three_Character_Code__c toCells="3,table873"}} 123 ➤ 1, 2, and 3 would be in separate table cells, which would each have the table873 CSS class applied to them. |
|
strip-html | The strip-html attribute will remove any HTML tags from data merged into your document from rich text fields.
Syntax: {{!Object.Field strip-html="True"}} |
|
justifyNewLines | The justifyNewLines attribute prevents irregular spacing when merging multi-paragraph long text area fields wrapped in justify tags. It causes each paragraph to be treated as its own paragraph.
Syntax: {{!Object.Field justifyNewlines=“HTMLElement”}} Example: INPUT: <div style=“text-align: justify;”>{{!Opportunity.Long_Text_Area__c justifyNewlines=“div”}}</div> OUTPUT: <div style=”text-align: justify;”>Paragraph One</div><div style=”text-align: justify;”>Paragraph Two</div> |
|
blobToString | The blobToString attribute converts HTML-based blobs into strings
Syntax: {{!Object.Field blobToString=“true”}} |
|
By default, S-Docs merges related lists into your template in the form of a table, where each record returned is generated as a row in the table. This means the table grows linearly with the number of records returned. In order to meet more specific formatting requirements, S-Docs has a variety of advanced attributes that can be leveraged.
Feature Name | Description |
DirectSOQL | Allows you to execute a custom SOQL query within your template and merge the resulting data into your document at runtime. DirectSOQL supports aggregates and subquery functions. |
Render | Provides ability to show/hide sections of a template based on a condition. |
Displaying Related Lists & SOQL Line Items Without Table Formatting
To remove the table formatting in a related list or SOQL table, you can place <class>none</class> at the beginning of your related list / SOQL code. For example, the following code will display account team members as a comma-delimited list rather than as a table:
<!--<lineitemsSOQL> <prefix>The Account Team Members are: </prefix> <class>none</class> <soql> SELECT user.name FROM accountteammember WHERE accountid='{{!account.id}}' </soql> <column postfix=", ">user.name</column> <postfix>. Please see page 3 for their contact information.</postfix> </lineitemsSOQL>-->
In this example, <class>none</class> removes all the table formatting. The postfix attribute adds a comma and a space between each account team member, but if we did not have this postfix attribute here, the items returned by the SOQL query might look something like this: Jack JohnsonJohn JacksonSarah McCleanJohn Paulson. This is because using <class>none</class> will make your SOQL query or related list return raw data with no spaces or table formatting, all on the same line.
Alternatively, if you need to format your related list data in an entirely new way, you can also generate a template component that formats your data and then merges it into your final document. Click here to read more about this feature.
Related List Column Attributes
Related lists contain columns that can optionally include additional attributes (shown in bold below). These attributes provide a powerful way to dynamically manipulate data to meet your requirements.
Column Attribute | Values | Description & Syntax | Examples & Notes |
---|---|---|---|
substitute | Comma-delimited list of key-value pairs. | Allows for replacing values with other values whenever a match is made. It checks the value against a series of values. If it is equal to a value, it returns the corresponding result. If it does not match, no substitution is made unless a final catch-all value is provided in the list.
Substitute functionality can be useful for translating values to different languages for a template. While you may be able to do the same using a Salesforce formula field, this can drastically reduce the number of formula fields you would need to create. Syntax: <column substitute="value1tomatch, value1ToSubstitute, value2ToMatch,Value2ToSubstitute, …, OptionalCatchall-substitution">Field__c </column> If the substitute list contains an odd number of values, then the last value will be the catch-all that is substituted when no matches are made. |
substitute="(1,one),(2,two),(3,three)"
<column substitute="2.00,2">quantity</column>
<column substitute="1, Januar, |
replaceall | Comma-delimited list of key-value pairs. | Allows for replacing values with other values. This is very similar to the substitute feature, with the following two exceptions:
1) substitute matches against (and replaces) the ENTIRE string, where as replaceall matches against (and replaces) all substring appearances of the specified string. 2) There is no "else" condition in replaceall (since we're replacing substrings, an "else" condition would be nonsensical) This attribute supports regexs. Syntax: <column replaceall="replaceThis1,replaceWithThis1,replaceThis2,replaceWithThis2,...replaceThisN,replaceWithThisN"> Regex Syntax: Start your replaceall string with [regex] (including brackets) For example, say you want to replace all "a) This is a test", "b) This is a test", etc. with " a) This is a test", " b) This is a test" but NOT replace anything that looks like "1. This is a test", "2. This is a test", etc. (i.e. you want to indent a) b) c) but not 1. 2. 3. and the data structure / related list formatting prohibit simpler solutions like using <li></li>). To achieve this, you could use the following: <column replaceall="[regex]([a-zA-Z]\)), $1">
|
If the data value is "Burlington Textiles Corp," but you want it to be "Boston Textiles Corp," use <column replaceall="Burlington,Boston"> |
showcolumn | Conditional statement | Allows you to conditionally show/hide a column.
Syntax: <column showcolumn="{{!Object.Fieldname}} == 'FieldValueThatTriggersColumnShowing'">...</column> Note that the column will be hidden if the syntax resolves to false. If your table has a header row, you will need to apply the same condition to the header row as a RENDER statement: <!--RENDER='{{!Object.Fieldname}}' == 'FieldValueThatTriggersColumnShowing'--><th>Column Name</th><!--ENDRENDER--> |
You can conditionally show an entire column in your related list if the Opportunity record's StageName field has a value of 'Prospecting' or 'Closed', and hide it if the StageName field has any other value, by using the following: <column showcolumn="({{!Opportunity.StageName}} == 'Prospecting' || {{!Opportunity.StageName}} == 'Closed')">...</column> |
type | "rtf", "text", "checkbox", or "radio" | If your field contains markup that you wish to preserve and display in your document, you can specify type="rtf"
This is useful for inserting blocks of information that already contains formatting/markup. If you wish to strip the HTML tags from your rich text field, you can specify type="text" If you want to display a checkbox or radio button image (checked and unchecked) rather than the database values of true/false or yes/no, you can use type="checkbox" or ="radio" Syntax: <column type="rtf">Your content goes here. </column> |
When using type ="checkbox" the checkbox images have a class called "sdcheckbox." If needed, you can modify the CSS treatment of the checkbox. E.g.
<style type="text/css">
|
header | String | Allows you to specify a header text.
Syntax: <column header="YourHeaderHere"> |
Example: <column header="Grand Total">will place "Grand Total" over that column as a header. |
format-number | Number | Allows you to format your column’s numbers to automatically include commas and periods.
Syntax: <column format-number="#,###.##"> |
Format number supports these four types:#,###
#,###.## #.### #.###,## For example, if a number in your column was stored as 123456 and |
format-date | Date, Date/Time | Allows Salesforce date and datetime fields to be formatted into any valid java pattern.
Syntax: <column format-date="MM/dd/yyyy"> |
To turn a date into just a day, month, or a year, you can use <column format-date="MMMMM"> (for days, use D, and for years, use Y) |
mergenext | Any value | Allows you to merge a cell with the cell to the right of it.
Syntax: <column mergenext="true"> |
If you have a currency symbol column and an amount column, like $ | 12$ | 4
$12 $4
Note: mergenext is not supported when using group-by functionality. |
colspan | Any value | Allows you to create a column that spans across multiple columns.
Syntax: <column colspan="4"> |
<column colspan="1"> has no effect; by default, a column already spans 1 column. <column colspan="4"> Will make this column span 4 columns total (i.e. this column will be 3 columns longer than it would normally be). This works the same as the HTML colspan attribute. |
newrow | Any value | Allows you to specify when to end the current row and create a new one.
Syntax: <column newrow ="4"> |
<column newrow="true"> Will create a new row for each record in this column. For example, instead of seeing cell 1 | cell 2 | cell 3 you will see cell 1 cell 2 cell 3----<column newrow="3"> Will create a new row after the 3rd record of each row, e.g. cell 1 | cell 2 | cell 3 cell 4 | cell 5 | cell 6 cell 7 | cell 8 | cell 9 This attribute is useful for creating documents such as mailing labels. |
prefix | Any value | Allows you to put a string at the beginning of each column.
Syntax: <column prefix="YourStringHere"> |
<column prefix="$"> would put a dollar sign at the beginning of each column like so:$ 12$ 4 |
nullprefix | Any value | If the content of a column is "null," this will swap null with a string or character of your choice at the beginning of your column.
Syntax: <column nullprefix="YourStringHere"> |
<column nullprefix="N/A"> will make columns with "null" values appear as N/A. |
postfix | Any value | Allows you to put a string at the end of each column.
Syntax: <column postfix="YourStringHere"> |
<column postfix="dollars"> would put "dollars" at the end of each column like so:12 dollars
4 dollars |
nullpostfix | Any value | If the content of a column is "null," this will swap null with a string or character of your choice at the end of your column.
Syntax: <column nullpostfix="YourStringHere"> |
<column nullprefix="N/A"> will make columns with "null" values appear as N/A. |
allprefix | Any value. | This replaces the need to use both prefix and nullprefix in the same template if they have equal values. If your template has both prefix and nullprefix set to the same value, you can replace them with this attribute.
Syntax: <column allprefix="YourStringHere"> |
<column allprefix="$"> will put "$" at the beginning of each column regardless of if the value is null or not. |
allpostfix | Any value | This replaces the need to use both postfix and nullpostfix in the same template if they have equal values. If your template has both postfix and nullpostfix set to the same value, you can replace them with this attribute.
Syntax: <column allpostfix="YourStringHere"> |
<column allpostfix="€"> will put "€" at the end of each column regardless of if the value is null or not. |
abfprefixouter | Any value | Allows you to put a string at the beginning of each column except the first one. The string will appear on the outside of the prefix attribute's contents.
Syntax: <column abfprefixouter=","> |
<!--{{! <lineitemsSOQL> <class>none</class> <soql>SELECT productcode FROM opportunitylineitem WHERE Opportunityid ='0061U0000078tEw' </soql> <column abfprefixouter=", ">productcode</column> <postfix>.</postfix> </lineitemsSOQL> }}-->This example would create a list of products that looks like:product1, product2, product3. |
startIndex | Any numerical value | Allows you to offset the beginning row number when you include the rownum column in your related list.
Syntax: <column startIndex="3"> |
Note that numbering starts at the number equal to the startIndex number + 1.
<lineitems> This example would output a table with row numbers beginning at 4. |
render | Comma-delimited list of render conditions & output values | Allows you to conditionally render different values in your related list columns.
Syntax: <column render="CONDITION_1,output_value_1,CONDITION_2,output_value_2...DEFAULT OUTPUT VALUE IF ALL RENDERS EVALUATE TO FALSE"> |
Examples: <column render="RECORD.Product_Type__c STARTSWITH Vacuum && RECORD.Product_Type__c ENDSWITH Cleaner,RECORD.Vacuum_Name__c,Not a Vacuum"></column>
<column render="RECORD.Title==null,No Title Available,RECORD.Title"></column>
You can also use nested render statements: <column render="RECORD.Country__c == usa,[RENDER1]RECORD.City__c == new york,S-Docs HQ,[RENDER2]RECORD.City__c == ann arbor,S-Docs Innovation Center,[ENDRENDER2][ENDRENDER1],Work From Home"></column>
<column type="rtf" render="RECORD.StageName == 'Closed', lt#span style='color:red;'gt# Closed lt#/spangt#,Open"></column>
|
breakeverynchars | Any numerical value | Inserts a line break after a specified character amount.
Syntax: <column breakeverynchars="10"> |
<column breakeverychars="10">Long_Line__c</column> will insert a line break after every 10 characters. |
addToEmail | "To", "CC", "BCC" | Adds email addresses merged through this column as document email recipients.
Syntax: <column addToEmail="To"> |
<column addToEmail="CC">CreatedBy.Email</column> will add the email addresses of every user who created a record in this related list as document email CC recipients |
blobToString | True | Converts HTML-based blobs into strings
Syntax: <column blobToString=“true”> |
|