Skip to main content

Stencil

docs image

Stencil

Manage the output of various stencils

EVA has a lot of functionalities where some form of user-friendly communication is desired. Think of invoices, thermal receipts, password reset mailings, end-of-day reports, click-and-collect order mailings and so on. When creating these outputs, we call them stencils and you manage them in its namesake chapter.

Building stencils requires knowledge about HTML, CSS and JavaScript. Some Stencils have been pre-built by our team for compliancy reasons, anything beyond what is pre-built is up to you.

Stencil basics

We call the chapter and the functionality it contains Stencil, but there will be many more definitions coming across your screen, so we'll start off explaining some of these definitions in their basic forms.

Template types

The basic idea behind stencil is super simple: you can build a stencil in our HTML editor, which consists of one or more of the following parts:

  • Template: a template is the foundation for your communication as it predetermines the data structure available to you. It is tied to its namesake event in EVA, such as a PickSlip, EmailValidation or PasswordResetRequested.
  • Partial: also a template, but you can see a partial as a snippet of one which you can inject in your main template. This means its goal is to make it easy for you to create reusable content.
  • Layout: a layout is also a reusable template, but focused on layout. Think of fonts and background color; mainly in HTML. This makes it especially well-geared towards use in HTML Mail templates.

The chapter itself is also split up in three separate tabs based on the above types.

Pre-made templates

Some templates come pre-configured, like the first ones you see in the overview.

In this case, they are CertifiedInvoices, which means they are pre-configured to be compliant. Aside from the header and footer, you cannot change these without losing compliance.


There are however more templates which come pre-configured with EVA, since they are necessary for specific functionalities. This is the case in for example the mailing of errors found during a product upload. This premade template is as neutral as can be - and should remain so.

You can however make new templates that rely on the neutral ones, but make them more suitable for specific OUs/languages.

Template

Because the Template tab contains all of the available functionality in this chapter, and Partial and Layout only have some of that functionality, we will walk you through this tab in its entirety.

It starts off with the following overview, showing you all configured stencils and their notable details.

The following fields are available when creating a template.


Stencil Name

When creating a new template, you have to specify a Name. This name is no free-form, but a dropdown list. These available names are directly tied to the template's corresponding event. Examples:

  • Invoice is the event where a customer requests an invoice by mail, giving you the invoice data allowing you to create a mail containing an invoice.
  • ThermalReceipt is the receipt that will be printed for in-store orders.
  • PasswordResetRequested contains among others a password token and URL to the related environment.

Naming in the other tabs

The other two tabs also require a Name, but this is just a (unique) name. Partials and layouts are not linked to a specific event, but to a template instead.

Stencil Destination

In addition to a Name, a Stencil has a Destination. This determines how EVA will try and process the template when the stencil is triggered.

The possible destinations are as follows:

  • Mail: the template will be sent out as an email
  • SMS: the template will go out as an SMS (see also: MessageBird)
  • PDF: the template will be converted/included as a PDF file
  • Thermal: the template will be be sent to a thermal printer
  • Notification: the template will be pused towards the Apps or POS (but can be used for a select group of templates only)
  • HTTP: EVA sends out all raw data, allowing you to create your own mails via an external tool (see also: Bypassing EVA and creating your own messages)

Destination details

Failing stencils

It is possible for stencils to fail: in case of Destination Thermal for example, EVA will send the template to a thermal printer, but it will fail if the printer is unavailable or unable to print the content.


Multiple destinations

To continue with that example: a ThermalReceipt Stencil requires you to set Thermal Printer as its Destination. Some Stencil Names can even support multiple destinations, for example: Invoice consists of two parts:

  • the Invoice Email
  • the Invoice PDF which will be included in the invoice e-mail as an attachment

When incorporating multiple destinations in one template, take into account that these will then both be based on the same Content. If you want the mail to be different from the PDF, create the same template twice: once with Mail and once with PDF as Destination.


Although it should be clear what kind of Destination(s) you need for what template in most cases based on its Name, we'll include several regularly-used templates, their purpose and the according destinations throughout these docs.

Thermal printer templates with other destinations

Some thermal printer templates, such as ThermalLastPinReceipt, can also print images when destination is set to HTTP or can be sent by mail when set to Mail.

Concept: Stencil matching

There are a few more properties available when creating your template:

  • Organization Unit
  • Country
  • Language

These determine what stencils to use when a trigger/event takes place. To make that clearer:

When an order is invoiced, EVA will check for the best Stencil match based on the organization unit that issues the invoice, the country in which the organization unit is located, and the language of the customer.

In these situations, Organization Unit trumps Country, and Country trumps Language.

The Content tab in any type of template is where you add and structure your actual code. This is where you add your header, footer and body. If required, this is where you include your partials and/or helpers (though those may already be included via the partial) as well.

The Header and Footer tabs may be slightly misleading: the practical header and footer (including financial information or an email sign-off for example) are included in the tab mentioned above, while these two tabs are explicitly used as technical header and footer when using PDF destinations. They allow you to add page numbering for example.

Use partials and layouts

There are many ways for you to structure your templates. You can configure your templates essentially from scratch, manually adding company details such as financial information or store details, or styling information such as HTML classes, but we'd recommend you do such kind of generic information via partials and layouts.

Helper functions

Stencil can be enriched with Helper functions, which are essentially JavaScript functions to support your HTML stencil. This allows you to create specific functions which you can then insert into any of your stencils.

Bear in mind though, that the helper function will be tied to the data model of the template you're including it in.

We will go into more detail on helpers by providing several examples in our Generic examples docs.


Sample data

Your templates are always triggered by a certain event in EVA, supported by a certain Data model. What data model this is, completely depends on your stencil Name. For example: the Invoice Template is backed up by the order data model, making a bunch of order properties available for display in your Stencil.

What the Sample data tab does, is take the data model's properties, and fill it up with mock-data. This will make your test templates look as real as possible.


Bypassing EVA and creating your own messages

Instead of having EVA create a stencil for you, you might want to create your own custom messages from scratch. In that case, choose the Destination HTTP.

By doing so, EVA will skip most steps in the stencil process and instead send all the raw data it would use to render the template to your endpoint. You can do this for all templates EVA offers, although it's most often used for invoices.

To set this up, take care of the following:

  • Add your endpoint in the Email:ExternalTemplateEndpoint setting (this can differ per OU)
  • Have your endpoint return a 200 message, to let EVA know the data's received and there's no need to retry the transmission
Pick either OU or Country level

This can be setup on OU or Country level by changing the Organization field as desired.