09 Custom Templates - ecellar/remote-widgets GitHub Wiki

The SPA uses 08 HTML Templates to render what is seen by your site visitors. If there are any templates that you would like to change, there are two things that you can do:

1. Add CSS to your site to adjust the styling of the templates.

and/or

2. Create new HTML templates to replace some of ours.

Typically, a lot can be done with just CSS. Simple changes can be made to modify the look/feel for all views or to modify the styling for specific views. If this is of interest to you, learn about how our 07 Themes work.

If a pure-CSS approach will not work for you, you can replace any template with a custom one.

1. Select the template to customize. See the 12 Template Directory for a list of templates.

2. Make a copy of the template file (save it to your PC for editing).

3. Review the template’s content and decide what to change.

Keep these requirements in mind:

a) All markup in the template must be wrapped by an HTML element (usually a div). For example, this is correct:

<div>
  <!-- some HTML -->
</div>

and this is not:

<div>
  <!-- some HTML -->
</div>
<div>
  <!-- some more HTML -->
</div>

b) Items in curly braces, like {message:first_name}, should be included in your custom template. These are replaced by the SPA when the template is rendered. For more information, see our 10 Content page.

c) CSS classes from our theme, such as ecp-component, ecp-summary, etc., are not required for the template to function. You may leave them out and/or use your own. For more information, see our 07 Themes page.

d) If an HTML <form> element is present in the default template, you must include it and all of the form elements (input, select, button, etc) that are inside of it in your custom template. The name attribute of all form fields must be kept as-is.

For example, if the template has:

<input type="text" name="username">

You must include the input with it’s name unchanged.

e) Elements with a data attribute name staring with “data-ecp-x-” are optional. These are typically special-purpose attributes that you can set a value for to override a default. For example: “data-ecp-x-limit” might be present to allow you to specify how many items appear in a list.

f) Elements with a data attribute name starting with “data-ecp-” must be included in your custom template. These are required for the template to operate.

Examples are:

data-ecp-id
data-ecp-key
data-ecp-handle
data-ecp-action

Note: in many cases the type of HTML element with a “data-ecp-” attribute does not matter. For example, if the template has this div:

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

And you would prefer to use a <span>, like this:

<span data-ecp-handle="products"> ... </span>

You can usually do so, but be sure to test your changes.

You should not change the element type of any form fields (input, select, textarea, etc).

Aside from the requirements above, you may reorganize/change the template as you see fit.

Important:

If you want to change the wording that appears in a template, we highly recommend that you use content placeholders rather than putting wording directly into a template. See our 10 Content page for more information.

4. To test your changes, you will need to:

a) Upload your template file to a location that can be accessed through the web.

b) Use the Designer Widgets addTemplates initialization option to tell the SPA to use your custom template.

Ideally, you will be able to test your changes using a development version of your site. If that is not available, you could create a “hidden” page on your site (a page that only you know the url for), instantiate the SPA there and use that to review and test your changes.

Note: some CMSes do not provide a way for an admin to upload an HTML file, then use it as HTML. In particular, we have found that Squarespace does not offer that functionality via the admin UI. If you are using Squarespace or another CMS that does not offer functioning file uploads, you will have to upload your files to somewhere else, then link to them in your SPA initialization options.

To learn more about integration with Squarespace, see our Using Squarespace page.

Here is an example for initializing the SPA with a reference to your custom template:

<script>
  epubOptions = {
    APIKey: '<provided by eCellar>',
    initQueryString: true,
    pathRoot: '/store/',
    addTemplates: [
      { 
        "cart": {
          "en": {
            "MiniCart": {
              "url": "<full url for your custom template>"
            }
          }
        }
      }		
    ]
  };
</script>

The relevant addTemplates bits are:

“cart”: the name of the widget that contains the template, in lower case.

You can find the widget name in the 12 Template Directory. Be sure to use a lower case version of the widget name. IE: “cart”, not “Cart”.

“en”: the language that will use your custom template.

Learn more about language support at our 10 Content page. In short: “en” stands for English.

“MiniCart”: the name of the template that you are replacing.

“url”: the full URL to your custom template.

For example, if your site is at https://<www.yoursite.com> and your custom template is located in a subdirectory there, use the full path to the file. Something like this:

"url": "https://<www.yoursite.com>/files/MiniCart.html"

To learn more about the addTemplates option, see our Initialization Options page.

5. Finalize your changes.

If you have been testing your changes using a development site or a hidden page on your production site, you should:

a) Make sure that your custom template is located at a url that you want to use for production.

b) Change your production SPA initialization options so that your custom template is used.

c) Verify that the changes appear and operate correctly.

If your custom template doesn’t work after you deploy it to production, you can remove it from your SPA initialization options, then troubleshoot the issue.