Develop personalization condition types

After developing widgets for Page Builder, you can enable content editors to personalize individual widgets. To set up personalization, you need to create the types of conditions based on which the widgets will be personalized.

The condition types may be of any kind or form, for example Current visitor belongs to contact group X, Current visitor has recently bought product X, or Current date is between X and Y. You can allow content editors to further adjust the conditions of specific widget variants by preparing properties and configuration dialogs for your condition types.

Create condition types

Conditions types are designed as global components and therefore must be registered in the your project’s application root (not in an Area). Registering condition types in Areas may lead to unexpected behavior.

To define a new personalization condition type:

1. Open your Xperience project in Visual Studio.

2. Create a class that represents and evaluates the condition type.

   • Place the condition type class into a component folder together with any other related files, for example ~/Components/PageBuilder/PersonalizationConditions/<condition type name>.
   • The condition type class needs to:
     • Inherit from the ConditionType base class (available in the Kentico.PageBuilder.Web.Mvc.Personalization namespace).
     • Override the Evaluate method, which determines whether the condition is met.

3. Specify additional properties in the class, representing options that content editors can configure for conditions of the given type.

   By default, the ConditionType base class contains the VariantName property that represents the name of the personalization variant. The base class implementation ensures that the value of the property is automatically displayed in the configuration dialog of personalization conditions. However, you can override the VariantName property if you wish to change the behavior or look of the property in the configuration dialog.

   When transferring data to and from the configuration dialog, the system serializes objects of the condition type class into JSON format (using the Newtonsoft.Json library).

   You can use the Newtonsoft.Json.JsonIgnore attribute to exclude properties from the serialized data (for example dynamically computed properties).

4. Define the visual interface of the condition type’s configuration dialog:

   • Decorate the specified properties using desired editing components.
   • The attribute assigns and configures a form component, which is used as the input element for the given property.
   Decorating condition type properties

   Copy

   
   
    // Assigns the default Xperience text input component to the property
    // Allows users to enter a text value for the given property in the configuration dialog
    [TextInputComponent(Order = 0, Label = "Consent code name")]
    public string ConsentCodeName { get; set; }
   
    

5. Register the condition type.

See a full example that demonstrates how to develop a basic condition type.

Conditions of the given type work according to your implementation of the Evaluate method. The configuration dialog is generated automatically based on the editing components assigned to the class’s properties.

Implement custom configuration dialogs

Custom configuration dialogs for personalization condition types are based on MVC architecture, composed of Model, View, and Controller elements. These elements define a configuration form which allows users to submit values for the condition type’s properties. By taking full control over the implementation, you can make the configuration dialog look and behave exactly as you need.

Place the configuration dialog classes into the condition type’s component folder, for example ~/Components/PageBuilder/PersonalizationConditions/<condition type name>.

Model

Create a model class containing the properties that you need to transfer to and from the configuration dialog’s view.

using System.ComponentModel.DataAnnotations;

namespace MyProject.Components.PageBuilder.PersonalizationConditions.HasGivenConsent
{
    public class HasGivenConsentViewModel
    {
        [Required]
        [Display(Name = "Consent code name")]
        public string ConsentCodeName { get; set; }
    }
}

Partial view

Create a partial view for the configuration dialog’s interface. The view needs to contain a form element that posts data to the validation action of the controller.

@model MyProject.Components.PageBuilder.PersonalizationConditions.HasGivenConsent.HasGivenConsentViewModel

<form asp-controller="HasGivenConsent" asp-action="Validate">
    <label asp-for="ConsentCodeName"></label>
    <br />
    <input asp-for="ConsentCodeName" />
    <br />
    <span asp-validation-for="ConsentCodeName"></span>
</form>

Controller

Create a controller class. The controller needs to inherit from the ConditionTypeController class (available in the Kentico.PageBuilder.Web.Mvcnamespace), with the condition type class as a generic parameter. The controller must contain the following actions:

• Index() – POST action displaying the configuration form. The action must return the form’s HTML content, typically a partial view. To display values of the condition type parameters when editing the form, you need to get the parameters and set them when creating the view model object.

• Validate(<model>) – POST action that receives the model of the configuration dialog as its parameter. Validate the model, and if successful, create an instance of the condition type class and serialize its data into JSON format by returning a new instance of the ConditionTypeValidationResult object. Upon unsuccessful validation or if any other error occurs, display the configuration dialog partial view with an appropriate error message.

  The VariantName property that represents the name of the personalization variant is implemented in the ConditionType base class by default. Make sure this property has a set value before you return the data.

  Example

  Copy

  
  
    public class HasGivenConsentController : ConditionTypeController<HasGivenConsentConditionType>
    {
        // Displays the configuration dialog
        [HttpPost]
        public ActionResult Index()
        {
            // Gets the condition's current configuration as an instance of the condition type class
            var conditionType = GetParameters();
  
            // Creates a view model object
            var viewModel = new HasGivenConsentViewModel
            {
                // Sets the consent code name obtained from the condition type parameters
                ConsentCodeName = conditionType.ConsentCodeName
            };
  
            // Displays the configuration dialog's view
            return PartialView("~/Components/PageBuilder/PersonalizationConditions/HasGivenConsent/_HasGivenConsentConfiguration.cshtml", viewModel);
        }
  
        // Submits the condition type parameters
        [HttpPost]
        public ActionResult Validate(HasGivenConsentViewModel model)
        {
            // Validates the model
            if (!ModelState.IsValid)
            {
                return PartialView("~/Components/PageBuilder/PersonalizationConditions/HasGivenConsent/_HasGivenConsentConfiguration.cshtml", model);
            }
  
            // Creates an object of the condition type class
            var parameters = new HasGivenConsentConditionType
            {
                ConsentCodeName = model.ConsentCodeName,
            };
  
            // Serializes the condition's configuration into JSON format and returns the data
            return new ConditionTypeValidationResult(parameters);
        }
    }
  
    

Register condition types

Register the condition type by adding an assembly attribute to the condition type class. Specify the following required attribute parameters:

• Identifier – the unique identifier of the condition type. We recommend using a unique prefix in your condition type identifiers to prevent conflicts when deploying condition types to other projects, for example matching your company’s name.
• Class type – the type (System.Type) of the condition type class.
• Display name – the name displayed in the condition type selector when personalizing widgets in the Xperience administration interface.
• (Required for condition types with a custom configuration dialog) Controller type – the type (System.Type) of the controller class used to display the configuration dialog.

Additionally, you can specify the following optional attribute parameters:

• Description – the description of the condition type displayed as a tooltip.
• IconClass – the font icon class displayed in the condition type selector.
• Hint – the text displayed as a hint above the condition type’s configuration dialog.

using Kentico.PageBuilder.Web.Mvc.Personalization;

[assembly: RegisterPersonalizationConditionType(
    identifier: "MyProject.Personalization.HasGivenConsentConditionTypeCustom",
    type: typeof(HasGivenConsentConditionTypeCustom),
    name: "Has given consent agreement (custom)",
    ControllerType = typeof(HasGivenConsentController),
    Description = "Evaluates whether the contact has given an agreement with a specified consent declaration.",
    IconClass = "icon-clipboard-checklist",
    Hint = "Enter the code name of a consent. The condition is fulfilled for visitors who have given an agreement with the given consent.")]

Once the condition type is registered, editors can select it when personalizing widgets in a website channel application within the Xperience administration.