Kibo spins off personalization business to focus solely on Commerce. Visit Monetate.com to learn more.

Kibo doubles down on eCommerce, Order Management, and Subscription Commerce. Learn More

Kibo Email Templates – Extending and Widgets

February 26, 2021
 
email templates development widgets commerce

Email is possibly the most aggravating part of web development (besides developing for older versions of different browsers). It’s the less “fun” aspect of web development. But working with email templates could be a nice workaround to the frustration.

As we know, there’s numerous limitations to email development because email clients and their rendering/parsing/filtering can be even more frustrating than needing a custom JavaScript library (Modernizr) or CSS comments (IE Only) to get clean, accessible, and aesthetically pleasing emails out the door.

For this reason, I tend to go with a nice “tried-and-true” method, using the email reset provided by MailChimp to help give us an email baseline reset CSS. (Callback: Eric Meyer’s reset CSS was the baseline for many an early web project). 

I know, some people love reinventing the wheel—but in this case, use the collective experience available to you and grab a prebuilt base to help give you a better starting point.

Email Templates in Kibo Commerce’s Site Editor

With our Core Theme (as of February 2021), Kibo presents you with 31 email templates covering several scenarios around Orders, Pickups, Notifications, Reminders, Returns, Shipments, Transfers, Stock notifications, and Curbside.

The full list can be viewed inside of Site Builder -> Editor under the folder “Email Templates.”

email templates
VSCode window showing order-shipped.hypr and a list of email templates

It’s all pretty basic from a development perspective: table-based layouts, simple classes, HYPR templating handling the simple logic of loops and if statements.

With these templates , you can build out your core email templates: the design (we’re extending this email template from the parent layout – email.hypr), the palette (Starting a design system? Are your classes named consistently so you can have primary/secondary actions consistently styled? Have you made sure banding fits your design’s needs), and, as a developer, dropzones can be dropped into the template to give business users additional customization beyond the base email.

Extending Your E-Mail Templates

Once you have checked out the HYPR reference and you see the dropzone tag, you can get an idea of what you can do inside of your template. It’s as simple as adding {% dropzone zoneId=“<a_unique_id>” %}.

Can Any Dropzone Be Added to an Email?

Out of the box, you could potentially add any existing widget to your dropzones. What I have found most effective is to create email-specific widgets (with an implied name, and sorting them accordingly in `theme.json`). To go the extra mile, I’ve made a habit out of attaching logic checks inside the widget themselves. As you should know, HYPR templates (not HYPR LIVE) are rendered server side, so they have access to the global variables of pageModel, siteContext, pageContext, navigation, user, categories, themeSettings, labels, routeData, and the model being passed in.

 We can use the pageModel a variety of properties being passed into it, in my example:

{
    "context": null,
    "output": null,
    "source": {
        "id": null,
        "listFQN": "emailTemplateContent@mozu",
        "path": "order.shipped",
        "documentTypeFQN": "emailTemplateContent@mozu",
        "includeInactiveDocument": true,
        "publishState": null
    },
    "zoneScope": "page",
    "widgetType": "content",
    "definitionId": "email-banner-image",
    "isRichText": false,
    "config": {
	// these are custom for the widget I created for an email example
        "emailBannnerImage": {
            "imageId": “unique-from-kibo”,
            "imageListId": "files@mozu",
            "altText": "",
            "width": "",
            "height": "",
            "imageUrl": “//our-cdn-url”
        },
        "emailBannnerDescription": "",
        "emailBannnerHeight": null,
        "emailBannnerDescriptionWidth": false,
        "emailBannnerURL": "",
        "emailBannnerFullwidth": false,
        "emailBannnerAddText": ""
    },
    "id": “unique-id-from-kibo”
}

Using this model, you’re able to create a check for the template:

{% if pageModel.source.listFQN == "emailTemplateContent@mozu" %}
	// the email widget code
{% else %}
    {% if pageContext.isEditMode %}
        THIS WIDGET IS ONLY AVAILABLE FOR EMAIL TEMPLATES
    {% endif %}
{% endif %}

Of course, you can do the reverse, to prevent any widgets that may require JavaScript from being dropped into an email template—if you need the extra defense for your business user. But you know your business users better than anyone, so plan accordingly, and put in the right safe guards that work best for them!