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.

HTML Syntax

  • 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.

ID and Class Nomenclature

  • 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.

Template HTML Classes

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.

Attributes Order

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

  1. class
  2. id, name
  3. data-*, data-evg-*
  4. src, for, type, href, value
  5. title, alt
  6. role, aria-*
  7. style

Campaign Stats Tracking

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.

Comments

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:

Visit the Handlebars documentation on template comments to learn more.

CSS Syntax

  • 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.

Declaration Order

Group properties by type, in the following order:

  1. Positioning
  2. Display / Box Model
  3. Color
  4. Text
  5. Other

Example:

Comments

Use /* ... */ for comments.

Single line:

Multiline:

ES Version

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

Syntax

  • 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.

    • SalesforceInteractions namespace
    • Evergage namespace

DOM Manipulation

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

  • SalesforceInteractions namespace

  • Evergage namespace

Visit the Cash documentation to learn more.

Deferred Rendering

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.

  • SalesforceInteractions namespace

  • Evergage namespace

Visit the Template Display Utilities documentation to learn more.

Comments

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.

Semantic Elements

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.

Making Accessible Color Choices

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: