Merge Syntax

What is Skuid Merge Syntax?

You’ll know it when you see curly brackets:

1
Name: {{First Name}} {{Last Name}}

What is it used for?

Inserting information into a template.

For more ideas on what’s possible with merge syntax, see the deep dive video on Youtube.

Important Terms

  • Curly brackets: Double or triple curly brackets (sometimes called “mustaches”). For example, in {{FirstName}}, “FirstName” is surrounded by curly brackets.

    Note

    What’s the difference between double and triple curly brackets?

    In most cases, double curly brackets in a template, for example {{Amount}}, tell Skuid to apply locale-specific formatting to the data, in other words, the formatting for the data field in the original data source object or entity. This means that {{3000}} might display in runtime as 3,000 (for data formatted as a count) or $3,000 (for data formatted as currency).

    Triple curly brackets, for example {{{Amount}}}, tell Skuid to display only the raw (unformatted) data. Therefore, {{3000}} displays as 3000, regardless of how the data field in the original object or entity was formatted.

  • Merges: Text wrapped within curly brackets, including the curly brackets themselves. For example, in Name: {{FirstName}} {{LastName}}, “{{FirstName}}” and “{{LastName}}” are both merges.

  • Template: A string of characters containing merges. For example, Name: {{FirstName}} {{LastName}} is a template.

  • Context: Context is especially important for merge syntax—without it, the merge will have no idea which data object to pull data from. A merge’s context could be model records, fields within records, or JavaScript objects (with or without properties). The context passed into the merge determines which variables are available to you. For more information, see the Skuid glossary.

Where are Templates used within Skuid?

  • Template Components: Skuid supports templates in many places, but the most common is the the Template Component.
  • Component Template Properties: Many of the properties for Skuid components support templates. For example, the Page Title Component supports templates in the Title and Sub-Title properties.
  • JavaScript: You can use Skuid’s JavaScript Merge API to perform Skuid Merges on any template you’d like using skuid.utils.merge( ).

Basic Syntax

An example of a basic template, which renders an Address for a User record:

1
2
3
{{Street}}
{{City}}, {{State}} {{PostalCode}}
{{Country}}

image0

More technical readers will notice that the rendered template includes the newline characters. Skuid automatically converts newlines into <br> tags so that they will be rendered properly on the page. This might not always be desired, especially if you are using a Template Component to emit HTML. To prevent this behavior from the Page Composer, you can check the “Allow HTML” option on the Template Component.

Dot Notation

You can use dot-notation to access sub-fields. For example, the following template is useful for displaying an image:

1
<img src="/servlet/servlet.FileDownload?file={{{Image__r.skuid__AttachmentId__c}}}"/>

In the above template, Image__r is a field belonging directly to the Model. The skuid__AttachmentId__c field belongs to the Image__r relationship, but can be accessed from Image__r using dot-notation.

HTML Escaping (and Not)

Notice that the above template uses three curly brackets rather than two, as the first template used. If you only use two curly brackets, you’ll probably end up with something like the following:

image1

Skuid automatically “HTML-encodes” content rendered from a double-curly bracket merge. This is useful because characters like “&”, “<” and “>” have special meaning in HTML and often don’t appear as expected if they aren’t “escaped”. For example, to display a “&” on a web page, you must use “&amp;” in the raw HTML. Skuid handles this conversion automatically, preventing special characters in your Model fields from causing major problems on the page.

In addition to HTML encoding, Skuid wraps double-curly bracket merge values in special <span> tags so that they can be re-extracted later.

This is useful for Field Editors that use templates, because it allows you to edit the individual fields within the template. For example, using the address template from the first example, we can create a Field Editor which, when clicked, produces a pop-up allowing the user to edit the individual Address fields:

image2

HTML-encoding and <span> tags can cause problems, though, when you are trying to create a template that displays HTML. Looking back at the first example, the image template is trying to inject a value into an HTML attribute. When the value is wrapped in a <span> tag, the <img> tag breaks creating a frustrating-looking broken image icon.

The solution is to use triple-curly bracket syntax. This tells Skuid not to use HTML-encoding. Skuid will also respect this syntax and render raw content which is not wrapped within <span> tags. Keep in mind, though, that if the content of the field contains special HTML characters, such as “&”, “<” and “>”, then you may end up with unexpected (and very messy) results.

Sections

Sections allow a limited form of conditional rendering within a template. To establish a section, based on a field named IsActive for example, you’d use the following syntax:

{{#IsActive}}Product is Active!{{/IsActive}}

If the IsActive field is missing or the value is false, 0, null, undefined, NaN, an empty string or an empty list, then the content contained between the IsActive tags will not be rendered.

If you only want to render content if the field’s value is one of the above “false-y” JavaScript values, you can use the following syntax:

{{^IsActive}}Product is not Active!{{/IsActive}}

You can use these two tags in combination to display a message based on whether a value is true or not, like so:

{{#IsActive}}Sell this product!{{/IsActive}}{{^IsActive}}Pretend this product doesn't exist!{{/IsActive}}

For example, the following template shows the quantity of a particular product and, if the quantity is non-null and greater than 0, a link to an Order Form:

{{Quantity__c}}{{#Quantity__c}} (<a href="/apex/orderForm?code={{{ProductCode}}}">Order Form</a>){{/Quantity__c}}

Looping over Arrays

If the target variable of a section is an “array” (a list of items), then the content of the section will be rendered once for each element in the array. For example, if using a template to render a child relationship in a Model, you can iterate over the records in the child relationship and display a template for each.

The following example iterates over the Pricebook entries for a Product and displays them in a bullet list:

<ul style="margin: 0; padding: 0;">
{{#PricebookEntries.records}}
<li>{{UnitPrice}} ({{Pricebook2.Name}})</li>
{{/PricebookEntries.records}}
</ul>

(To further enhance the appearance of the list, check “Allow HTML” to prevent Skuid from inserted <br> tags in place of newlines).

Notice that within the section, tags are relative to the current element. So, rather than {{PricebookEntries.records.UnitPrice}}, we use simply {{UnitPrice}}.

(Skuid stores child records in a special property of the field named records; “records” is not a template keyword.)

This template will generate a <ul> tag, followed by a <li> tag for each child object, followed by a closing </ul> tag. The result looks something like this:

image3

Using Templates from JavaScript

To use Skuid Templates from JavaScript, you can call Skuid’s version of the Mustache renderer via skuid.utils.merge.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var model = skuid.model.getModel( 'User' ),
   row = model.getFirstRow();

var addressTemplate =
   '{{Street}}\\n' +
   '{{City}}, {{State}} {{PostalCode}}\\n' +
   '{{Country}}';

element.html(
   skuid.utils.merge( 'row', addressTemplate, null, model, row )
);

Skuid’s merge syntax is built on MustacheJS. If you want to use the Mustache API directly (to access pre-parsing, for example), you can access the API via skuid.Mustache. Note that you will not be able to use some of Skuid template features, such as Skuid’s Merge Variables.

Troubleshooting

  • If you are using sections to help determine a Data Source URL parameter for a REST model, you may experience unexpected behavior. If you are encountering issues, try renaming the field or adjusting your merge syntax.