Migrating of custom page builder selectors to native XbyK components

[bluemodus-mwills]

Motivation

Many KX13 projects use custom page builder components to provide selectors in widget properties.

However, Xperience by Kentico introduces new, superior content selectors. So, instead of migrating the KX13 custom page builder selectors to XbyK, we'd like to migrate page builder configurations to use XbyK's native field types and selectors. This will ensure customers who migrate from KX13 have the best experience with Xperience by Kentico.

KX13 example

For example, many of our KX13 projects use a custom page builder form component to provide a custom tree node selector.

The widget properties are configured like this:

[EditingComponent(TreeNodeSelectorComponent.IDENTIFIER, Label = "Content to Display", Order = 0)]
[EditingComponentProperty(nameof(TreeNodeSelectorComponentProperties.ClassNamesToDisplay), new[]
{
    CmsContentTypes.Folder.CLASS_NAME
})]
[EditingComponentProperty(nameof(TreeNodeSelectorComponentProperties.ClassNamesSelectable), new[]
{
    ContentTypes.Feature.CLASS_NAME,
    ContentTypes.NavigableItemBase.CLASS_NAME
})]
[EditingComponentProperty(nameof(TreeNodeSelectorComponentProperties.AllowMultiple), true)]
[EditingComponentProperty(nameof(TreeNodeSelectorComponentProperties.AllowDerivedClasses), true)]
public string SelectedNodeGuids { get; set; }

The provided selector property looks like this:

And, the values stored in the widget property look like this (a comma-delimited node list):

"properties": {
    "selectedNodeGuids": "5ae5f7eb-d25d-44d0-bcbb-356cd98a4633,334c61ec-9d06-4dd6-9289-990ee26c0674,8e3fb419-1fc5-472d-9d23-c3986ab1a6e1,f38d9ab0-5a17-42d9-a041-91b627f53e47,d8aab096-9406-41ed-85bc-a4f145af48de,1f526bef-222c-4c79-bc9e-6354abda5779",
}

XbyK Example Conversion

To prevent having to port an inferior, custom page builder component to XbyK, and to provide XbyK customers an optimal experience, we'd like to translate such legacy widget properties to use a native XbyK property component, like the ContentItemSelectorComponent or WebPageSelectorComponent.

Here's what the above property definition would look like if translated to use a ContentItemSelectorComponent :

[ContentItemSelectorComponent(
    Feature.CONTENT_TYPE_NAME,
    ExplanationText = "Create or select a Feature to display.",
    Label = "Content to Display",
    MinimumItems = 0,
    MaximumItems = 20,
    Order = 4)]
public IEnumerable<ContentItemReference> SelectedFeatures { get; set; } = Enumerable.Empty<ContentItemReference>();

And, here's what the above sample property value would look like if translated to a property using the ContentItemSelectorComponent selector:

{
    "selectedFeatures": [
        {
            "identifier": "5ae5f7eb-d25d-44d0-bcbb-356cd98a4633"
        },
        {
            "identifier": "334c61ec-9d06-4dd6-9289-990ee26c0674"
        },
        {
            "identifier": "8e3fb419-1fc5-472d-9d23-c3986ab1a6e1"
        },
        {
            "identifier": "f38d9ab0-5a17-42d9-a041-91b627f53e47"
        },
        {
            "identifier": "d8aab096-9406-41ed-85bc-a4f145af48de"
        },
        {
            "identifier": "1f526bef-222c-4c79-bc9e-6354abda5779"
        }
    ]
}

Proposed solution

An ideal solution would allow users of the Migration Tool to register a custom class in a discoverable assembly, so that the component is called when a page builder widget configuration is discovered in the source KX13 database. The Migration Tool would provide information about the page builder property, including its value and the selector used for the value. The custom component would return data that instructs the Migration Tool on how to translate the values of the widget property.

Alternative solution

Allow the community to add migration code for common, community created page builder components to the Migration Tool.

[tkrch]

@bluemodus-mwills thanks for report, i will mark this as related to #238.

Basically this would mean exposure of widget definition inside page builder definition and page template definition.

I need to do further investigation and approval from repo owner before implementation, I will be back with result.

[tkrch]

Hi @bluemodus-mwills, customization feature for widget property migrations is currently under review in PR #263.

Feel free to check if feature implements Your needs.

Samples to check (https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/tree/feat/239_widget_custom_pb_migrations/Migration.Tool.Extensions#custom-widget-property-migrations):

1. WidgetFileMigration
2. WidgetPageSelectorMigration
3. WidgetPathSelectorMigration

[bluemodus-mwills]

Thank you, @tkrch. This looks great. It took me a bit to get my head around it. I had to remember that selector and property definitions are changed in code, so this extension only has to handle the values. This looks wonderful. We will use this in almost every migration, because we have custom selectors built for KX that will be replaced by native Xperience by Kentico selectors.

Thank you!!!