08 HTML Templates - ecellar/remote-widgets GitHub Wiki

The Designer Widgets system includes a set of views that are rendered by the SPA using HTML templates. Each view has a main template.

Some views also have sub-templates. Sub-templates are usually used to render an array of items inside the main template. Occassionally sub-templates are used to break a very large main HTML template into smaller parts.

Here is a main HTML template that has one sub-template:

<div class="ecp-component ecp_CategoryWithProducts">
  <h2>{message:category_name}</h2>
  <div class="ecp-html-content">{message:display_html}</div>
  <div data-ecp-handle="products">
    <!-- | CategoryWithProducts__Product template | -->
  </div>
</div>

Things to know:

1. All templates (mains and subs) have an outer HTML element (usually a div) that acts as a wrapper for the contents of the template. In this case, our wrapper opens with:

<div class="ecp-component ecp_CategoryWithProducts">

and closes with:

</div>

2. CSS class names are NOT used for anything other than styling. You could remove all of them and the template would still work.

See our 07 Themes page for information about styling.

3. Items with curly braces, like this: {message:category_name} are used by the SPA to insert data or words when the template is rendered.

See our 10 Content page for information about content.

4. HTML elements with a data-ecp-handle attribute are used by the SPA to “get a handle” on the element so that it can be used for something.

For example, in the case above, we have this:

<div data-ecp-handle="products">

The SPA code that uses this template will look for the HTML element with the “products” handle and will render an array of products inside of it.

5. Our example template uses a sub-template to render each product. The name of the sub-template is provided in an HTML comment for your reference, like this:

<!-- | CategoryWithProducts__Product template | -->

The comment does not play any functional role; it’s there to make it easier for you to figure out what sub-template will be used in that part of the main HTML template.

See the CategoryWithProducts__Product template.

You’ll probably notice that more is going on in that sub-template, compared to our main template. In general, though, it’s adhering to the same rules that the main template adheres to.

6. Sub-templates can also use other sub-templates. For example, the sub-template above uses a sub-template to render an array of HTML option elements inside a select element.

<!-- | CategoryWithProducts_Option template | -->

See the CategoryWithProducts__Option template

See the 12 Template Directory for a list of all templates.

Go to the 09 Custom Templates page to learn about customizing templates.