Preparing email widgets

Email widgets in Kentico represent reusable pieces of code that can be easily manipulated by business users. This allows for greater flexibility when composing marketing emails. Email widgets need to be placed in email widget zones, defined in individual email templates.

You can manage email widgets in the Email marketing application on the Email widgets tab.

Creating email widgets

To create a new email widget for use in marketing emails:

1. Open the Email marketing application and switch to the Email widgets tab.

2. Click New email widget.

3. Specify the display name.

4. (Optional) Set the email widget thumbnail (a custom image or a font icon).

   • Thumbnails are used to represent individual email widgets when listed on an email’s Email builder tab.

5. Click Save.

   • The system creates the email widget and opens its Widget editor tab.

6. Write the code of the email widget in the code editor.

   • You can see the macros specifically available for email marketingin the email marketing macro reference.

7. Click Save.

8. (Optional) Define email widget properties on the Properties tab for greater customization options.

Now that you have created the email widget, you need to assign it to the email template you are going to use when composing marketing emails. For an example demonstrating the email widget creation process, see the example below.

Defining email widget properties

Widget properties are parameters that can be defined for individual email widgets. Users can set the values of the email widget properties when composing marketing emails, allowing for greater customization and reusability of each email widget. Email widget properties can be accessed through the macro engine and manipulated via macro syntax.

To define email widget properties:

1. On the Email widgets tab, edit () an email widget or create a new one.
2. Switch to the Properties tab.
3. Define email widget properties via the field editor.

You can now manipulate defined email widget properties in the code editor on the widget’s Widget editor tab.

Assigning email widgets to email templates

To be able to work with email widgets when creating marketing emails, you first need to assign the widgets to the email templates you are going to use for your marketing emails.

You can assign widgets to email templates either via the widget’s Assigned to email templates tab, or the email template’s Available widgets tab.

Assigning email widgets via the Assigned to email templates tab

1. Open the Email marketing application and switch to the Email widgets tab.
2. Edit() the email widget you want to assign to a template.
3. Switch to the Assigned to email templates tab.
4. Click Add templates.
5. Select the email templates you need to assign and click Select.

Assigning email widgets via the Available widgets tab

1. Open the Email marketing application and switch to the Email templates tab.
2. Edit () the template of the Email type that you want to assign the widgets to.
3. Switch to the Available widgets tab.
4. Click Add widgets.
5. Select the widgets you need to assign and click Select.

Now that you have assigned the widgets to the email templates, you can use them when composing marketing emails on an email’s Email builder tab.

Personalizing email widgets

You can personalize emails by defining which users (recipients) are able to see specific email widgets. We recommend defining the visibility of email widgets based on user personas.

Personalizing email widgets based on Personas

1. Open the Email marketing application and switch to the Email widgets tab.

2. Edit() the email widget you want to personalize.

3. Switch to the Properties tab.

4. Click New field and create a field with the following settings:

   • Field name: Personas
   • Data type: Text
   • Field caption: Personas
   • Form control: Uni selector (select via the (more items…) option)
   • Object type:Personas.Persona
   • Return column name: PersonaGUID
   • Selection mode: Multiple

5. Click Save.

6. On the Widget editor tab, wrap the widget’s existing code into a conditon that checks the value of the Personas property:

   Example

   Copy

   
   
   
    {% if(Recipient.IsInPersona(Personas)) { %}
   
        // Main widget code
        ...
    {% } #%}
   
   
    

7. Click Save.

When composing marketing emails on an email’s Email builder tab, you can now select multiple Personas for the widget. The widget’s content will then be visible only for recipients who belong to one of the given personas.

Example – Creating a custom email widget

This example demonstrates how to create a new email widget acting as a link. Users will be able to modify the target URL and the displayed text when editing a marketing email and placing the widget in an email widget zone.

1. Open the Email marketing application and switch to the Email widgets tab.

2. Click New email widget.

3. Type Customizable link button as the Display name.

   • The system automatically generates a Code name based on the Display name.

4. Click Save.

   • The system creates the email widget and opens its Widget editor tab.

5. Switch to the Properties tab and create the following fields:

   • Field name: TargetUrl
   • Data type: Long text
   • Required: Selected
   • Field caption: Target URL
   • Field description: Enter a target URL.
     
     
   • Field name: DisplayText
   • Data type: Text
   • Default value: Click me!
   • Field caption: Display text
   • Field description: Enter a display text.

6. On the Widget editor tab, copy the following code to the editor:

   Custom email widget markup

   Copy

   
   
   
    <a href="{% TargetUrl %}" class="button">{% DisplayText %}</a>
   
   
    

   Note

   All necessary CSS and JavaScript markup needs to be included as part of the email template the email widget is assigned to.

7. Click Save.

The Customizable link button email widget is now ready. Users can modify the target link and the displayed text when composing a marketing email and working with the widget on the email’s Email builder tab.