Web Templates Style Guide and Coding Conventions

This document shares best practices that Marketing Cloud Personalization template developers follow for writing consistent HTML (Handlebars), CSS, and JavaScript code. Use this documentation as a guide for developing your own templates.

Indent nested elements 4 spaces (one press of the TAB key in the template editor).
Break long lines to improve readability, up to 120 characters maximum per line. Place HTML attributes that extend beyond 120 characters on a new continuation line, indented 4 spaces.
Use double quotes ( "" ) instead of single quotes ( '' ) for HTML attributes, as shown in the following example.
Contain all the handlebars HTML content within a single element.
Write all code in lowercase, including HTML element names, attributes, and attribute values.
Use HTML elements for their designed purpose. Whenever possible, use semantic elements that describe the meaning of the content. See the section on "Accessibility" for more details.

Add an ID attribute to the outermost element, using a name specific to the template being built, and prefix with the evg- namespace (for example, id=“evg-hero-banner”). Use an ID for only this outermost HTML element and do not use the same ID in more than one template.
Use classes for all other nested elements. Prefix classes with the evg- namespace (for example, class=“evg-btn”).
Use hyphens to separate words in class and id names.

For suggested evg- prefixed class names and descriptions of their intended purpose, as well as examples of CSS styling, refer to Template HTML Classes and CSS.

List your HTML attributes in the following order to improve readability.

class
id, name
data-*, data-evg-*
src, for, type, href, value
title, alt
role, aria-*
style

If you would like to track campaign stats with Personalization, use the data attributes (data-evg-*) available in the Handlebars HTML. These data attributes require that the Campaign Stat Tracking gear is installed and enabled for your dataset.

Example:

See the Campaign Stats article on this site to learn more.

For comments you wish to keep in the Handlebars-generated HTML output, use the native HTML comment format:

For comments you wish to remove in the resulting HTML output, use the following Handlebars HTML comment format.

Any Handlebars HTML comment that includes double curly braces or Handlebars expressions must adhere to the following format. These comments also do not appear in the resulting HTML output:

For more information, see the Handlebars documentation on template comments.

Place the leading brace on the same line as the selector.
Add one space between the colon and value of each property. No space before the colon.
For each declaration, indent 4 spaces (one press of the TAB key in the template editor) and include a single space after the colon. End each declaration with a semicolon ( ; ). Add a blank line between rulesets.
Add one space before the leading brace.
Use the ID selector of the outermost element for every CSS rule to scope them all to the specific template. Use classes instead of element names as selectors that follow the ID selector.
When using multiple selectors for a ruleset, give each selector its own line.
Write code in lowercase, including selectors, properties, and property values (except for strings).
Avoid using element names in conjunction with IDs or classes. Also avoid using ancestor selectors unless necessary.
Don't add units for "0" values, unless required.
Don't add leading zeros in property values.

Group properties by type, in the following order:

Positioning
Display / Box Model
Color
Text
Other

Example:

Use /* ... */ for comments.

Global templates are written in ES6 syntax. Use ES5 syntax if there are plans to support IE browsers.

Indent nested elements by 4 spaces (one press of the TAB key in the template editor).
Break long lines to improve readability, up to 120 characters maximum per line (including whitespace).
Add spaces between curly brackets and their contents.
No spaces between square brackets and their contents.
No spaces between parentheses and their contents.
No space between the function name and opening parenthesis of the argument list.
Add one space before the leading brace.
Add one space before the opening parenthesis in conditional statements.
When chaining more than two methods, separate each method by a new line and use indentation.

Use cashDom to select and manipulate elements from the DOM in a similar fashion to jQuery.

Visit the Cash documentation to learn more.

Depending on the SDK namespace you're using, use SalesforceInteractions.DisplayUtils.pageElementLoaded or Evergage.DisplayUtils.pageElementLoaded to defer the rendering of the template until the content zone element is loaded on page. To use this utility, you must have the Display Utilities gear installed and enabled for your dataset.

The observer element that monitors for the content zone element to get inserted into its DOM node is set to "body" by default. For performance optimization, this default can be overridden by adding a second selector argument, which is used as the observer element instead.

Visit the Template Display Utilities documentation to learn more.

Follow the JSDoc standards for adding JavaScript documentation comments.

Use //... for inline comments.

Use /** ... */ to comment code blocks, placed it immediately before the block being documented. For multi-line comments, align the stars by indentation.

Document code blocks with one or more JSDoc tags to describe the function.

See the complete list of JSDoc tags.

Use HTML elements for their designed purpose. Whenever possible, use semantic elements to describe the meaning of the content to developers and the browser when appropriate. For example, use heading elements such as h1, h2, and so on to identify headings, anchor elements (a) for navigation between pages, button elements (button) for actions like opening a modal, and input elements (input) for submit buttons (with the type="submit" attribute).

Semantic element examples:

button
h1
form
header

Non-semantic element examples:

div
span

If you use non-semantic elements instead of semantic elements, add ARIA attributes to provide more meaning to the element. For example, if you use a div element instead of the h1 element as a level 1 heading and there is more than one heading on the page, add the role="heading" and aria-level="<heading level number>" ARIA attributes to the non-semantic element (for example, <div role="heading" aria-level="1">Page Heading</div>). Doing so allows assistive technologies like screen readers to identify the non-semantic element as a heading.

Provide an alt attribute for all image elements. In case an image fails to load, the text alternative can convey the meaning of the image in its place (for example, alt="Woman with a shopping cart"). Aim for succinct, descriptive text. If the image is used purely for decoration and is not informative, set the alt tag to an empty string (for example, alt="") so that it can be ignored by assistive technologies. Do not leave out the alt attribute as some screen readers resort to announcing the file name of the image.

For close buttons ('X') such as those commonly used in popups, use a button element (button) with an aria-label attribute (for example, aria-label="Close") to provide an accessible name.

The WAVE Evaluation Tool Chrome extension is useful for evaluating the accessibility of your site.

For more information on accessibility, visit Web Content Accessibility Guidelines.

Ensure that the colors chosen for the text and background satisfy the color contrast ratio as recommended by Web Content Accessibility Guidelines (WCAG). Aim for a color contrast ratio of 4.5 or higher for normal text and 3 for larger text (18 px in bold or 24 px). Visit the WCAG documentation on minimum contrast to learn more.

Use a tool like aremycolorsaccessible.com to check that the color ratio meets at least the AA level.

When using a background image as the backdrop for text, set a fallback background color in case the image does not load. Choose the fallback color such that the text is still visible and the colors meet the color contrast ratio requirements.

Example: