Developing personalization condition types

After developing widgets for the 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 is in persona 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.

Creating condition types

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

To define a new personalization condition type:

1. Open your MVC project in Visual Studio.

2. Create a class that represents and evaluates the condition type. The recommended location for condition type classes is the ~/Personalization/ConditionTypes folder.

3. 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.

4. Specify additional properties in the class, representing the 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).

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

   • Decorate the specified properties using the EditingComponent attribute (available in the Kentico.Forms.Web.Mvc namespace).

   • The attribute assigns and configures a form component, which is used as the input element for the given property.

     Note: To learn about the available options when using and configuring editing components, see Assigning editing components to properties.

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

6. 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 EditingComponent attributes that you specified for the class’s properties.

Creating condition types with a custom configuration dialog

In addition to condition types with an automatically generated configuration dialog, you can implement your own custom configuration dialogs that exactly match your condition type’s requirements.

To define a new personalization condition type with a custom configuration dialog:

1. Create a class that represents and evaluates the condition type. The recommended location for condition type classes is the ~/Personalization/ConditionTypes folder.
   • Follow the instructions from the Creating condition types section, but without decorating the class’s properties using the EditingComponent attribute.
2. Develop Model/View/Controller elements that handle the custom configuration dialog of the condition type. See Implementing custom configuration dialogs.
3. When registering the condition type, you need to specify the Controller type attribute parameter.

Implementing custom configuration dialogs

Custom configuration dialogs for personalization condition types are 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.

Model

Create a model class containing the properties that you need to transfer to and from the configuration dialog’s view. The recommended location is the ~/Models/Personalization/ConditionTypes folder.

using System.ComponentModel.DataAnnotations;

namespace LearningKit.Personalization.ConditionTypes
{
    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 recommended location is the ~/Views/Shared/Personalization/ConditionTypes folder.

The view needs to contain an MVC form element that posts data to the validation action of the controller.

@model LearningKit.Personalization.ConditionTypes.HasGivenConsentViewModel

@using (Html.BeginForm("Validate", "HasGivenConsent"))
{
    @Html.LabelFor(model => model.ConsentCodeName)
    <br />
    @Html.EditorFor(model => model.ConsentCodeName)
    <br />
    @Html.ValidationMessage("ConsentCodeName")
}

Controller

Create a controller. The recommended location is the ~/Controllers/Personalization/ConditionTypes folder.

The controller needs to inherit from the ConditionTypeController class (available in the Kentico.PageBuilder.Web.Mvc namespace), with the condition type class 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, serialize it into JSON format using the Json method, and return the data. 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 serialize and 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("Personalization/ConditionTypes/_HasGivenConsentConfiguration", viewModel);
            }
  
            // Submits the condition type parameters
            [HttpPost]
            public ActionResult Validate(HasGivenConsentViewModel model)
            {
                // Validates the model
                if (!ModelState.IsValid)
                {
                    return PartialView("Personalization/ConditionTypes/_HasGivenConsentConfiguration", 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 Json(parameters);
            }
        }
  
  
  
    

Registering 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 Kentico 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("LearningKit.Personalization.HasGivenConsentConditionTypeCustom", 
    typeof(HasGivenConsentConditionTypeCustom), "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 the Pages application within the Kentico administration interface.