Skip to main content

Viewer String Helpers

String helpers let you format and manipulate text in Viewer templates. Use these helpers to transform text from Salesforce fields—like names, addresses, emails, and descriptions—into properly formatted content for your documents.

Whether you need to normalize casing, trim whitespace, shorten long text, or replace characters, Viewer's string helpers give you precise control over how text appears in generated PDFs and documents.

If you need to display a Salesforce long text field with line breaks preserved, start with nl2br. It is the most important helper for multi-line descriptions, notes, comments, and long text area fields in PDF and Word output.

Function name meaning (quick reference)​

  • nl2br = preserve line breaks in Salesforce long text and multi-line text fields
  • lowercase = convert text to lower case
  • uppercase = convert text to upper case
  • capitalize = make first letter upper case
  • titleize = capitalize each word
  • trim = remove spaces at start/end
  • truncate = shorten text to a max length
  • replace = replace part of a string with another value
  • startsWith = check if text starts with a value
  • endsWith = check if text ends with a value

nl2br​

Converts newline characters to format-specific break tags so Salesforce long text fields keep their line breaks in generated documents.

What it does:

  • Keeps the line breaks that users entered in Salesforce
  • Works for both PDF and Word output
  • Helps long text fields display more naturally in the final document

When to use: Display multi-line Salesforce fields like Description, Notes, Comments, or Long Text Area fields without losing line breaks.

Scenario: Display a Salesforce long text field properly in both PDF and Word output.

Example: PDF format for Salesforce long text field
{{nl2br Account.Description "PDF"}}
Example: Word format for Salesforce long text field
{{nl2br Account.Description "Word"}}

Expected result:

  • PDF format: The text keeps the same line breaks entered in Salesforce
  • Word format: The text also keeps the same line breaks entered in Salesforce
Best use case for nl2br

Use nl2br whenever you display a Salesforce long text field that includes line breaks and you want the document output to match what users entered in Salesforce.

lowercase​

Converts all text to lowercase letters.

Scenario: Normalize email display or make text consistent.

Example: Field-based
{{lowercase Contact.Email}}
Example: Literal text
{{lowercase "JOHN.DOE@COMPANY.COM"}}

Expected result: john.doe@company.com

uppercase​

Converts all text to uppercase letters.

Scenario: Highlight reference codes or create bold headings.

Example: Field-based
{{uppercase Account.CustomerCode}}
Example: Literal text
{{uppercase "customer ref-12345"}}

Expected result: CUSTOMER REF-12345

capitalize​

Capitalizes only the first character, leaving the rest unchanged.

Scenario: Make stage labels or field values easier to read.

Example: Field-based
{{capitalize Opportunity.StageName}}
Example: Literal text
{{capitalize "qualification stage"}}

Expected result: Qualification stage

titleize​

Capitalizes the first letter of each word (title case).

Scenario: Format product names, categories, or headings.

Example: Field-based
{{titleize Product2.Family}}
Example: Literal text
{{titleize "enterprise software solutions"}}

Expected result: Enterprise Software Solutions

trim​

Removes whitespace (spaces, tabs, newlines) from the beginning and end of text.

Scenario: Clean data imported from external systems or user input.

Example: Field-based
{{trim Account.Name}}
Example: Literal text
{{trim "   Acme Corporation   "}}

Expected result: Acme Corporation

When to use trim

Always use trim on fields that might contain extra whitespace from imports, integrations, or manual data entry.

truncate​

Shortens text to a maximum length. Adds "..." at the end if text is cut.

Syntax: {{truncate value length}}

Scenario: Keep long descriptions compact in tables or summaries.

Example: Field-based
{{truncate Opportunity.Description 50}}
Example: Literal text
{{truncate "This is a very long product description that needs to be shortened for display" 30}}

Expected result: This is a very long product...

Truncate length

The length parameter includes the "..." characters. Choose lengths like 50, 80, or 120 based on your document layout.

replace​

Replaces all occurrences of one string with another.

Syntax: {{replace value "find" "replaceWith"}}

Scenario: Format IDs, clean data, or substitute characters.

Example: Field-based
{{replace Account.External_Id__c "_" "-"}}
Example: Literal text
{{replace "Ref_NUM_12345" "_" "-"}}

Expected result: Ref-NUM-12345

Common uses for replace
  • Convert underscores to hyphens or spaces
  • Remove unwanted characters
  • Standardize formatting across different data sources

startsWith​

Checks if text starts with a specific string. Use with conditional blocks.

Syntax: {{#startsWith value "prefix"}}...{{/startsWith}}

Scenario: Show conditional content based on prefixes or codes.

Example: Conditional display
{{#startsWith Account.Name "ENT-"}}
  Enterprise Account - Priority Support Included
{{/startsWith}}
Example: Using with literal text
{{#startsWith "ENT-ACME-001" "ENT-"}}
  This is an enterprise account
{{/startsWith}}

Expected result: This is an enterprise account (content displays because string starts with "ENT-")

endsWith​

Checks if text ends with a specific string. Use with conditional blocks.

Syntax: {{#endsWith value "suffix"}}...{{/endsWith}}

Scenario: Show conditional content based on file extensions or suffixes.

Example: Conditional display
{{#endsWith ContentDocument.Title ".pdf"}}
  PDF Document - Signed Copy Available
{{/endsWith}}
Example: Using with literal text
{{#endsWith "Contract_Final.pdf" ".pdf"}}
  This is a PDF file
{{/endsWith}}

Expected result: This is a PDF file (content displays because string ends with ".pdf")

Combining String Helpers​

You can combine helpers for more complex transformations.

Example: Clean and capitalize
{{capitalize (trim Account.Name)}}
Example: Uppercase and replace
{{uppercase (replace Account.Code__c "_" "-")}}
Helper order matters

When combining helpers, inner helpers execute first. For example: {{uppercase (trim " hello ")}} → trims first → then converts to uppercase → HELLO

Document Formatting Helpers​

These helpers format text output for document rendering in PDF and Word formats.

preserveLineBreaks​

Preserves line breaks in text using Word XML formatting (always Word format).

From implementation behavior:

  • Converts all newline characters to Word XML <w:br/> sequences
  • Useful when you always output to Word documents
  • Simpler than nl2br since Word format is implicit

When to use: Format text for Word document output where consistent line-break preservation is needed.

Scenario: Display account notes with proper line breaks in Word documents.

Example: Field-based
{{preserveLineBreaks Account.Notes}}

Expected result: Line breaks preserved in Word XML format

Common Use Cases​

How do I format names consistently?​

Use titleize to capitalize each word in a name:

{{titleize Contact.Name}}

For all caps: {{uppercase Contact.Name}}

How do I clean up imported data with extra spaces?​

Use trim to remove leading and trailing whitespace:

{{trim Account.Name}}

For fields that might have inconsistent spacing, always apply trim before other formatting.

How do I shorten long descriptions for tables?​

Use truncate with an appropriate length:

{{truncate Opportunity.Description 80}}

Choose truncation lengths based on your layout:

  • Short labels: 30-50 characters
  • Table cells: 80-100 characters
  • Summaries: 120-150 characters

How do I replace characters in field values?​

Use replace to substitute one string for another:

{{replace Account.Phone " " "-"}}

Common uses:

  • Convert underscores to hyphens: {{replace value "_" "-"}}
  • Remove parentheses: {{replace value "(" ""}} and {{replace value ")" ""}}
  • Standardize separators: {{replace value "/" "-"}}

How do I show content conditionally based on text patterns?​

Use startsWith or endsWith with conditional blocks:

{{#startsWith Account.Type "Enterprise"}}
  Premium support package included
{{/startsWith}}

{{#endsWith Attachment.Name ".pdf"}}
  Ready for digital signature
{{/endsWith}}

How do I format multi-line descriptions for PDF output?​

Use nl2br helper with "PDF" format:

{{nl2br Opportunity.Description "PDF"}}

Result: Newlines become <br/> HTML tags

How do I format multi-line text for Word documents?​

Use nl2br helper with "Word" format:

{{nl2br Opportunity.Description "Word"}}

Result: Newlines become Word XML </w:t><w:br/><w:t> sequences

How do I format notes while avoiding undefined field errors?​

Combine nl2br with isTruthy to handle missing data:

{{#isTruthy Account.Notes__c}}
{{nl2br Account.Notes__c "PDF"}}
{{else}}
No notes on record.
{{/isTruthy}}

How do I handle special characters (ampersands) in formatted text?​

The nl2br helper automatically escapes ampersands (& → &amp;) to prevent XML issues:

{{nl2br "Project A & Project B
Status: In Progress" "Word"}}

Result: Ampersands properly escaped, newlines converted.

Best Practices​

  • Use one helper per line for clarity—nesting is powerful but can be hard to debug
  • Apply helpers to direct fields (e.g., Account.Name) rather than complex expressions
  • Choose appropriate truncation lengths based on your document layout (50, 80, 120 chars)
  • Always test with real data to ensure formatting works with edge cases
  • Combine with trim when working with imported or user-entered data

More resources​