Module: Email Builder

5 of 13 Pages

Set up properties for an article widget

✖
Copy to clipboard

Email Builder in Xperience by Kentico allows marketers to design emails using a drag-and-drop interface. By creating custom widgets, developers can extend the functionality of Email Builder to meet specific project requirements.

Let’s explore how to create an Email Builder widget for displaying articles. The example here uses tools and follows conventions from our Xperience Email Builder Starter Kit.

Configure allowed content types

To ensure the widget can select only articles, start by configuring the allowed content types.

For this example, we want our widget to be portable to other solutions, so we’ll go through extra steps to create options for developers to configure during startup, and use them in a filter.

This way, any project with some kind of article, blog post, or news-like content type can configure the widget with minimal code changes. Then, we’ll go through an example using the TrainingGuides.ArticlePage content type from the Training guides repository.

If your widget does not need to be shared with other projects, you can simply hard-code the available content types in the content item selector that we will use later on.

Define options for allowed content types

Start by adding a new file called TrainingGuidesEmailBuilderOptions.cs in the ~/Features/Shared/EmailBuilder folder. This options class will allow developers to specify the content types marketers can select in the widget properties.

C#
TrainingGuidesEmailBuilderOptions.cs 

namespace TrainingGuides.Web.Features.Shared.EmailBuilder;

public class TrainingGuidesEmailBuilderOptions
{
    public IEnumerable<string> AllowedArticleContentTypes { get; set; } = Array.Empty<string>();
}

Register the options

Add the options to the AddTrainingGuidesOptions method in ~/ServiceCollectionExtensions.cs, found in the root of the TrainingGuides.Web project. If this method does not exist, create it.

C#
ServiceCollectionExtensions.cs 

...
public static void AddTrainingGuidesOptions(this IServiceCollection services)
{
    ...
    services.Configure<TrainingGuidesEmailBuilderOptions>(options =>
    {
        options.AllowedArticleContentTypes = [ArticlePage.CONTENT_TYPE_NAME];
    });
    ...
}
...

Then, call this method from Program.cs immediately after AddTrainingGuidesServices.

C#
Program.cs 

...
builder.Services.AddTrainingGuidesServices();
builder.Services.AddTrainingGuidesOptions();
...

Implement a content type filter

Next, let’s create a filter that uses the TrainingGuidesEmailBuilderOptions to restrict the widget’s selectable content types.

Add a file called ArticleContentTypesFilter.cs in the ~/Features/Articles/EmailWidgets folder.

Then, implement the IContentTypesFilter interface. Use dependency injection to resolve the options we configured during startup.

Use the provided codenames to find the GUIDs of the corresponding data classes and assign them to the AllowedContentTypeIdentifiers property.

C#
ArticleContentTypesFilter.cs 

using CMS.DataEngine;
using Kentico.Xperience.Admin.Base.FormAnnotations;
using Microsoft.Extensions.Options;
using TrainingGuides.Web.Features.Shared.EmailBuilder;

namespace TrainingGuides.Web.Features.Articles.EmailWidgets;

/// <summary>
/// Article content types filter.
/// </summary>
internal sealed class ArticleContentTypesFilter : IContentTypesFilter
{
    /// <summary>
    /// Content type GUID identifiers allowed for <see cref="ArticleWidget"/>.
    /// </summary>
    public IEnumerable<Guid> AllowedContentTypeIdentifiers { get; }

    /// <summary>
    /// Article content types filter.
    /// </summary>
    /// <param name="trainingGuidesEmailBuilderOptions">The email builder options, configured at startup.</param>
    public ArticleContentTypesFilter(IOptions<TrainingGuidesEmailBuilderOptions> trainingGuidesEmailBuilderOptions)
    {
        var codeNames = trainingGuidesEmailBuilderOptions.Value.AllowedArticleContentTypes;

        AllowedContentTypeIdentifiers = DataClassInfoProvider.ProviderObject.Get()
            .WhereIn(nameof(DataClassInfo.ClassName), codeNames)
            .Column(nameof(DataClassInfo.ClassGUID))
            .GetListResult<Guid>();
    }
}

Define the widget properties

Now, we need widget properties, where marketers can enter data to configure the widget.

For the sake of simplicity in this example, let’s use a single property that allows users to select an article. We should be able to gather all the information the widget needs from the selected article.

Create a file called ArticleEmailWidgetProperties.cs in the ~/Features/Articles/EmailWidgets folder:

Remember to assign the content type filter from earlier to the selector.

C#
ArticleEmailWidgetProperties.cs 

using CMS.ContentEngine;
using Kentico.EmailBuilder.Web.Mvc;
using Kentico.Xperience.Admin.Base.FormAnnotations;

namespace TrainingGuides.Web.Features.Articles.EmailWidgets;

/// <summary>
/// Configurable properties of the <see cref="ContentWidget"/>.
/// </summary>
public sealed class ArticleEmailWidgetProperties : IEmailWidgetProperties
{
    [ContentItemSelectorComponent(
        contentTypeFilter: typeof(ArticleContentTypesFilter),
        Label = "Select article",
        ExplanationTextAsHtml = true,
        ExplanationText = "The widget will display the content from the selected article.",
        Order = 10,
        MaximumItems = 1)]
    public IEnumerable<ContentItemReference> ArticlePage { get; set; } = [];
}

You can find details about the various form controls available for Email Builder component properties in the documentation.

5 of 13