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.
   C#

   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.

Register condition types

Register the condition type by adding the RegisterPersonalizationConditionType 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.

Additionally, you can specify the following optional attribute parameters:

• Description – the description of the condition type displayed as a tooltip.

• IconClass – the icon displayed in the condition type selector. The value must be a font icon class from the set of icons starting with the icon- prefix. Alternatively, you can pick the icon from the pre-packaged, annotated list of icons that’s part of the KentiCopilot initiative.

• 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.HasGivenConsentConditionType",
    type: typeof(HasGivenConsentConditionType),
    name: "Has given consent agreement (custom)",
    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.