Add a custom dropdown provider for administration components

When editors create pages with Page Builder, they utilize components (page templates, sections, widgets), prepared by the developers. Each component has properties, that editors set in the Xperience administration using UI controls, for example, a dropdown selector.

As a developer, you can populate an Xperience dropdown selector with data in two ways:

1. Pass a “hardcoded” string of options, as you can see in this example.

2. Create a dropdown provider that maps options dynamically.

This guide covers the second approach. In our example, we use enumeration to define the dropdown options.

Prerequisites

This guide assumes you have:

• basic knowledge of C# and .NET framework concepts
• familiarity with the basics of Page Builder in Xperience by Kentico

If you’d like to follow along with the example discussed in this guide, the main branch of our training guides repository is a great starting point.

Implement a generic mapper class

1. Create a generic DropdownEnumOptionProvider class that:

   • implements IDropDownOptionsProvider
   • accepts struct and Enum as the generic type
   If you are working in the training guides repository, we recommend placing the class inside ~/Features/Shared/OptionProviders folder in the TrainingGuides.Web project.

2. Implement the following methods:

   1. GetOptionItems
      • tells Xperience how to map the enumeration members to dropdown items.
   2. Parse
      • casts a string value to the enumeration type. The value from the dropdown selector control comes back as string by definition, so the method will come in handy later in your code.
   To work with enumerations, this guide’s example uses EnumsNET NuGet package. The library allows you to access the enumeration attributes, like Description, which is handy, for example, to store UI labels for each dropdown option.

Below is a complete code of a generic DropdownEnumOptionProvider class, for your reference:

using System.ComponentModel;
using EnumsNET;
using Kentico.Xperience.Admin.Base.FormAnnotations;

namespace TrainingGuides.Web.Features.Shared.OptionProviders;

public class DropdownEnumOptionProvider<T> : IDropDownOptionsProvider
    where T : struct, Enum
{
    public Task<IEnumerable<DropDownOptionItem>> GetOptionItems()
    {
        // map enum members to DropDownOptionItem
        var results = Enums.GetMembers<T>(EnumMemberSelection.All)
            .Select(enumItem =>
            {
                // dropdown item label:
                // if available, use Description attribute, otherwise use enum item name
                string text = enumItem.Attributes
                    .OfType<DescriptionAttribute>()
                    .FirstOrDefault()?.Description
                    ?? enumItem.Name;
                
                // dropdown item value 
                string value = enumItem.Value.ToString();

                return new DropDownOptionItem { Value = value, Text = text };
            });

        return Task.FromResult(results.AsEnumerable());
    }
 
    public virtual T Parse(string value, T defaultValue) =>
        Enums.TryParse<T>(value, true, out var parsed)
            ? parsed
            : defaultValue;
}

Use the new mapper class

Let’s demonstrate the enumeration mapping on an existing dropdown selector property of the Landing page template in the main branch of our training guides repository.

Define your enumeration

1. Examine the LandingPageTemplateProperties.cs file in TrainingGuides.Web/Features/LandingPages. The dropdown values are currently defined by a string constant:
   C#LandingPageTemplateProperties.cs - BEFORE MAPPING

   Copy

   
   ...
   private const string OPTIONS =
       "H1;Heading 1" + "\n" +
       "H2;Heading 2" + "\n" +
       "H3;Heading 3" + "\n" +
       "H4;Heading 4" + "\n" +
       "P;Paragraph" + "\n";
   
   [DropDownComponent(
       Label = "Message tag type",
       Options = OPTIONS,
       ExplanationText = DESCRIPTION)]
   public string MessageType { get; set; } = "H4";
   ...
   

2. Define the LandingPageHeadingTypeOption enumeration accordingly.
   C#

   Copy

   
   public enum LandingPageHeadingTypeOption
   {
       [Description("Heading 1")]
       H1,
       [Description("Heading 2")]
       H2,
       [Description("Heading 3")]
       H3,
       [Description("Heading 4")]
       H4,
       [Description("Paragraph")]
       P
   }
   

Map the enumeration to the dropdown component

1. Assign the type of DropdownEnumOptionProvider<YOUR_ENUMERATION> to the DataProviderType property of the DropDownComponent.
2. Remove the Options property, which is no longer needed.

   using System.ComponentModel;
using Kentico.PageBuilder.Web.Mvc.PageTemplates;
using Kentico.Xperience.Admin.Base.FormAnnotations;
using TrainingGuides.Web.Features.Shared.OptionProviders;
using TrainingGuides.Web.Features.Shared.OptionProviders.Heading;

namespace TrainingGuides.Web.Features.LandingPages;

public class LandingPageTemplateProperties : IPageTemplateProperties
{
    private const string DESCRIPTION = "Select the type of Html tag that wraps the home page message";

    [DropDownComponent(
        Label = "Message tag type",
        ExplanationText = DESCRIPTION,
        DataProviderType = typeof(DropdownEnumOptionProvider<LandingPageHeadingTypeOption>)
    )]
    public string MessageType { get; set; } = nameof(LandingPageHeadingTypeOption.H2);
}

// enumeration defining the dropdown values and labels
public enum LandingPageHeadingTypeOption
{
    [Description("Heading 1")]
    H1,
    [Description("Heading 2")]
    H2,
    [Description("Heading 3")]
    H3,
    [Description("Heading 4")]
    H4,
    [Description("Paragraph")]
    P
}

If you followed along with the example above, run the TrainingGuides.Web project. When you edit the Home page template in the Xperience administration, the Message tag type property should let you change the style of the “Welcome to Training guides!” message - the same way as before the refactor.

What’s next

You can now utilize the DropdownEnumOptionProvider class across your project, for dropdown selector properties of page templates, Page Builder sections, or widgets alike. As later guides in this series demonstrate, you can work with enumerations that are shared or reuse other enumeration values.

If you’d like to read more about how to approach working with Page Builder in Xperience by Kentico projects, Meet business requirements with Page Builder provides a great introductory explanation.

The next guide of this series will walk you through the process of creating versatile page templates.