Managing templates

Permission required

This action can be performed by users with the Manage templates permission.

NewStore uses customizable document templates to generate digital or print communication for customers during order placement, checkout, shipping, and processing.

In NewStore, you can render templates into 2 types of documents: HTML and text. You can also convert some of these documents into PDF format for printing. For example, financial and fulfillment documents are converted to PDF when a printout is requested.

To generate templates, you can either use the Templates Editor in NewStore Omnichannel Manager, or create templates programmatically via an API.

Important

NewStore only supports templates that are less than 1 MB in size. Documents exceeding this size are not generated.

Template types and properties

Depending on the document type to generate from a template, you may have to work with one or more templates. For example, email templates are divided into a subject template and an email body template.

Push notification templates are typically in JSON format and SMS templates are typically a string.

Each template has pre-defined properties. The properties depend on the template type. For example, some templates do not allow you to display the payment method used for an order.

Customizing a template

Once you know the properties and identifiers that you want to update in your template, you can start customizing it.

Important

To update certain documents to be generated correctly, you may have to update more than one template using the Templates Editor. For more information on which templates are to be used or updated to send specific documents or notifications to customers, see this table .

For example, for emails to be sent to the customer for a successful refund, use or update the following templates:

• refund_note
• refund_note_email
• refund_note_subject

To update a template:

1. Go to Tools > Templates Editor.

2. From the Template drop-down menu, select the template that you want to update.

3. From the Output Type drop-down menu, select if you want the output to be in HTML or PDF format.

4. From the Locale drop-down menu, select the locale for which you want to update the template.

5. In the Template tab of the editor, make any required changes to the content of the template.

6. In the Schema tab of the editor, check the JSON Schema for validating the data before rendering the template.

7. To view the properties that the selected template contains, select the Sample Data tab in the editor. You can use this tab as a reference to make changes in the Template tab.

   note

   The Sample Data tab also displays example data for each property that the template contains.

8. In the Helper functions tab of the editor, read more about Jinja custom functions and filters for Templates-API.

9. To preview the template, select the Preview tab of the editor.

   If you have selected PDF as the output format for your template, you can also download a PDF version of the generated preview document by clicking Download PDF.

10. To compare the changes made to the original version of the template with the current version, select the Show Diff tab of the editor.

    The changes are displayed as highlighted text in the editor.

11. To verify the changes you have made to the template, in the Publish tab, click Verify changes.

    The Show Diff tab displays the changes in highlighted text. Ensure that you verify the changes made before moving on to the next step.

12. To publish the new template, in the Publish tab, click Publish new template.

    Important

    Ensure that you know what you are doing. Once the changes to a template are published, you cannot undo them.

    If you provide CSS or fonts hosted by an external source, ensure the external source is highly reliable. If the resource cannot be downloaded, it will be ignored, and the template will be rendered with a default CSS or font.

    We suggest providing a fallback font in your font-family CSS definition and testing your template with the fallback font.

    Example:

    @font-face {
    font-family: 'YourFontName';
    url('http://domain.example/fonts/font.ttf');
    }
    
    body {
      font-family: 'YourFontName', Arial, Helvetica, sans-serif;
    }

    The unavailability of external resources may lead to the generated document looking different than usual. For example, the printed receipt the customer receives may look different.

    To find out which external resource is currently unavailable, we recommend checking the error logs in the template editor in Omnichannel Manager.

This tutorial is only meant for updating templates via an API. However, you can refer to it for more information on best practices, FAQs, and pre-defined functions when using the template editor.

Identifying template errors

A template may not render due to various issues such as a typo in a variable identifier or macro call, a missing import, or even missing data. NewStore collects the errors that occur during the template rendering flows. You can see the errors that happened in the in the past 48 hours in the templates editor.

To see the latest errors in the templates editor:

1. Go to Tools > Templates Editor.

2. The message Checking for template errors will be displayed under the page's title.

3. If no errors are found the message No errors found will be displayed.

4. The message X template errors found. See errors will be displayed when errors are found.

5. Click on See errors to see a table with the latest error messages, the time when they occurred, the request ID and the identification of the template and locale where the error happened.

6. Click on the template name to load it in the editor.

Related topics

• Customizing templates
• Tutorial: Creating templates