Transform widget properties

This technical deep dive shows you how to transform widget properties during an upgrade from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK). You’ll learn how to migrate properties that use different UI controls, handle custom components, and enhance the editing experience by restructuring widget properties.

While the Kentico migration tool handles most standard widget properties automatically, you often need to customize the migration process when working with complex property configurations or when modernizing widgets as part of the upgrade.

For comprehensive widget restructuring scenarios, see our Migrate widget data as reusable content page. This material focuses on property-level transformations.

Understand the mechanics

Before exploring specific transformation scenarios, it’s important to understand how widget property migration works. Generally, upgrading widget properties involves two key aspects: data migration and code migration.

Data migration handles the transformation of existing widget property data from your KX13 database to the new XbyK structure. Most widget properties are straightforward to handle and migrate automatically as they map one-to-one between KX13 and XbyK (e.g., text fields) or have a default migration defined (e.g., pages, attachments/media files).

For properties you wish to modify, you need to define your own custom widget property migration. You can do this for properties using out-of-the-box UI controls and custom controls alike.

Code migration involves updating your widget property classes to use XbyK’s new form component attributes and APIs. When you use source instance API discovery, you’ll need to adjust your widget properties to utilize the new controls. This is a straightforward and methodical process, where AI assistance can help – at least for the out-of-the-box UI controls.

If your widgets use any custom UI controls, you’ll need to re-implement them in the target solution.

Now let’s walk through concrete examples that demonstrate different types of property transformations.