Editing components in Xperience by Kentico

In Xperience by Kentico, editing components are no longer only used when configuring Page Builder and Form Builder components. Instead, you can use them across the entire Xperience administration (e.g., in content types, UI form components, validation and visibility conditions, custom configuration dialogs).

A consequence of this broadened scope is that the Kentico Xperience 13 approach of assigning and configuring editing components via the EditingComponent attribute is now obsolete. Editing components in Xperience by Kentico, though functionally mostly equivalent, use a different technology stack to integrate with the new administration interface.

The old API remains supported and is fully backward compatible, including modal dialog support. However, this may eventually change. For this reason, we strongly recommend updating your codebase to the new components.

See:

• Editing components for more information about the new API used to assign editing components.
• Reference - Admin UI form components for a reference of all components usable in the admin UI.

For details about updating form components in general, see Form components. For details about updating selector components, see the following sections: 

• Page selector
• URL selector
• Object selector
• General selector
• Media file selector
• Path selector
• Attachment selector

Form components

In Kentico Xperience 13, you assigned editing components using the EditingComponent attribute and configured them via the EditingComponentProperty attribute.

using Kentico.Forms.Web.Mvc;

// Assigns the 'TextAreaComponent' as the editing component of the 'Text' property
[EditingComponent(TextAreaComponent.IDENTIFIER)]
[EditingComponentProperty(nameof(TextAreaProperties.Placeholder), "Enter your text here...")]
public string Text { get; set; }

In Xperience by Kentico, each editing component has a dedicated attribute that allows you to configure all properties in the constructor.

Update the code by mapping the corresponding EditingComponentProperty calls to individual attribute constructor parameters. Keep in mind that some properties may be renamed, changed, or added in the new product:

using Kentico.Xperience.Admin.Base.FormAnnotations;

// Assigns the 'TextAreaComponent' as the editing component of the 'Text' property
[TextAreaComponent(WatermarkText = "Enter your text here...")]
public string  Text { get; set; }

Selectors

Page selector

In Kentico Xperience 13, you assigned the page selector using the EditingComponent attribute and configured it via the EditingComponentProperty attribute.

using Kentico.Forms.Web.Mvc;
using Kentico.Components.Web.Mvc.FormComponents;

[EditingComponent(PageSelector.IDENTIFIER)]
[EditingComponentProperty(nameof(PageSelectorProperties.RootPath), "/Articles")]
[EditingComponentProperty(nameof(PageSelectorProperties.MaxPagesLimit), 0)]
// Returns a list of page selector items (node GUIDs)
public IEnumerable<PageSelectorItem> Pages { get; set; } = Enumerable.Empty<PageSelectorItem>();

In Xperience by Kentico, the page selector has a dedicated WebPageSelectorComponent attribute that allows you to configure all properties in the constructor. Also, the return type was changed to a collection of WebPageRelatedItem objects.

Update the code by mapping the corresponding EditingComponentProperty calls to individual attribute constructor parameters. The properties of the returned object were not changed and will be updated automatically: 

using System.Collections.Generic;
using System.Linq;

using CMS.Websites;

using Kentico.Xperience.Admin.Websites.FormAnnotations;

// Returns a list of selected page items (node GUIDs)
[WebPageSelectorComponent(RootPath = "/Articles", MaximumPages = 5)]
public IEnumerable<WebPageRelatedItem> Pages { get; set; } = Enumerable.Empty<WebPageRelatedItem>(); 

URL selector

In Kentico Xperience 13, you assigned the URL selector using the EditingComponent attribute and configured it via the EditingComponentProperty attribute.

using Kentico.Forms.Web.Mvc;
using Kentico.Components.Web.Mvc.FormComponents;

[EditingComponent(UrlSelector.IDENTIFIER)]
[EditingComponentProperty(nameof(UrlSelectorProperties.Tabs), ContentSelectorTabs.Attachment | ContentSelectorTabs.Media)]
[EditingComponentProperty(nameof(UrlSelectorProperties.MediaAllowedExtensions), ".gif;.png;.jpg;.jpeg")]
[EditingComponentProperty(nameof(UrlSelectorProperties.AttachmentAllowedExtensions), ".gif;.png;.jpg;.jpeg")]
[EditingComponentProperty(nameof(UrlSelectorProperties.MediaLibraryName), "Graphics")]
// Returns a string containing the relative URL of the selected page
public string Url { get; set; }

In Xperience by Kentico, the URL selector contains a few changes:

• you can only use it to select page URLs. Attachments and files from media libraries are not supported. If you have page or page template configurations with media file URLs stored using the selector, the data persists until users make a different selection using the new selector and save the changes.
• the URL selector now has a dedicated UrlSelectorComponent attribute that allows you to configure all properties in the constructor. However, due to the reduction in available selection scopes, the selector no longer allows you to configure the:
  1. available selection tabs, previously set via UrlSelectorProperties.Tabs.
  2. extension filter for selectable types of media files and attachments, previously set via UrlSelectorProperties.MediaAllowedExtensions and UrlSelectorProperties.AttachmentAllowedExtensions.
  3. filter for media libraries from which users can select the media files, previously set via UrlSelectorProperties.MediaLibraryName.

The following snippet shows an example of the new usage:

using Kentico.Xperience.Admin.Content.FormAnnotations;

// Returns a string containing the relative URL of the selected page
[UrlSelectorComponent(Label = "Select a page")]
public string PageUrl { get; set; }

Object selector

In Kentico Xperience 13, you assigned the object selector using the EditingComponent attribute and configured it via the EditingComponentProperty attribute.

using Kentico.Forms.Web.Mvc;
using Kentico.Components.Web.Mvc.FormComponents;

[EditingComponent(ObjectSelector.IDENTIFIER)]
[EditingComponentProperty(nameof(ObjectSelectorProperties.ObjectType), "cms.user")]
[EditingComponentProperty(nameof(ObjectSelectorProperties.WhereConditionProviderType), typeof(ObjectWhere))]
[EditingComponentProperty(nameof(ObjectSelectorProperties.OrderBy), new string[] { "UserName DESC" })]
public IEnumerable<ObjectSelectorItem> Users { get; set; } = Enumerable.Empty<ObjectSelectorItem>();

public class ObjectWhere : IObjectSelectorWhereConditionProvider
{
    // Where condition limiting the selectable objects     
    public WhereCondition Get() => new WhereCondition().WhereStartsWith("UserName", "a"); 
}

In Xperience by Kentico, the object selector has a dedicated ObjectSelectorComponent attribute that allows you to configure all properties in the constructor. Also, the return type was changed to a collection of ObjectRelatedItem objects.

To update the code, map the corresponding EditingComponentProperty calls to individual attribute constructor parameters:

using Kentico.Xperience.Admin.Content.FormAnnotations;

[ObjectSelectorComponent("cms.user", WhereConditionProviderType = typeof(ObjectWhere), OrderBy = new string[] { "UserName DESC" })]
public IEnumerable<ObjectRelatedItem> Users { get; set; } = Enumerable.Empty<ObjectRelatedItem>();

public class ObjectWhere : IObjectSelectorWhereConditionProvider
{
    // Where condition limiting the selectable objects
    public WhereCondition Get() => new WhereCondition().WhereStartsWith("UserName", "a");
}

General selector

In Kentico Xperience 13, you assigned the General selector using the EditingComponent attribute and configured it via the EditingComponentProperty attribute.

[EditingComponent(GeneralSelector.IDENTIFIER)]
[EditingComponentProperty(nameof(GeneralSelectorProperties.DataProviderType), typeof(UserGeneralSelectorDataProvider))]
public IEnumerable<GeneralSelectorItem> UserOptions { get; set; } = Enumerable.Empty<GeneralSelectorItem>();

In Xperience by Kentico, the General selector has a dedicated GeneralSelectorComponent attribute that allows you to configure all properties in the constructor. Instead of returning a collection of GeneralSelectorItem objects, General selector now returns a collection of string objects, which contain the values of the selected items.

// Assigns the General selector as the property's editing component
[GeneralSelectorComponent(
            dataProviderType : typeof(UserGeneralSelectorDataProvider),
            Label = "Users",
            Placeholder = "Choose a user")]
public IEnumerable<string> UserOptions { get; set; }

Media file selector

In Kentico Xperience 13, you assigned the Media file selector using the EditingComponent attribute and configured it via the EditingComponentProperty attribute.

using Kentico.Forms.Web.Mvc;
using Kentico.Components.Web.Mvc.FormComponents;

[EditingComponent(MediaFilesSelector.IDENTIFIER)]
[EditingComponentProperty(nameof(MediaFilesSelectorProperties.LibraryName), "Graphics")]
[EditingComponentProperty(nameof(MediaFilesSelectorProperties.MaxFilesLimit), 5)]
[EditingComponentProperty(nameof(MediaFilesSelectorProperties.AllowedExtensions), ".gif;.png;.jpg;.jpeg")]
// Returns a list of media files selector items (objects that contain the GUIDs of selected media files)
public IEnumerable<MediaFilesSelectorItem> Images { get; set; } = Enumerable.Empty<MediaFilesSelectorItem>();

In Xperience by Kentico, the Media file selector has a dedicated AssetSelectorComponent attribute that allows you to configure all properties in the constructor.

Due to the changed return type of the component (MediaFileSelectorItem changed to AssetRelatedItem), you need to perform the following steps:

1. Replace the EditingComponent attribute with the AssetSelectorComponent attribute.
2. Map the corresponding EditingComponentProperty calls to the individual constructor parameters.
   • Filtering selection to specific libraries via the LibraryName property is currently not available in Xperience by Kentico.
3. If there are instances of the currently updated component already in use, you need to update the saved configuration of any existing instances.
   1. Decorate the affected model classes with the UseMediaFileValueProcessor attribute and rebuild your project. 2. Re-save the configuration of the component:
   • For widgets in the Page Builder, open the respective page, edit it, and save it.
   • For form components in the Form Builder, open the form and perform any change to force an autosave. 3. Remove the UseMediaFileValueProcessor attribute from the model class.

using Kentico.Xperience.Admin.Base.Forms;
using Kentico.Xperience.Admin.Content.FormAnnotations;

using Kentico.Builder.Web.Mvc;

[UseMediaFileValueProcessor]
public class WidgetModelClass : IWidgetProperties
{
    // Returns a list of media files selector items (objects that contain the GUIDs of selected media files)
    [AssetSelectorComponent(MaximumAssets = 5, AllowedExtensions = "gif;png;jpg;jpeg")]
    public IEnumerable<AssetRelatedItem> Images { get; set; } = Enumerable.Empty<AssetRelatedItem>();
}

Path selector

There are no plans to make the path selector available in Xperience by Kentico.

If you need to retrieve a collection of tree paths, we recommend using the Page selector and obtaining paths from the selected pages:

// Retrieves the GUIDs of the selected pages from the 'Pages' property
List<Guid> pageGuids = model?.Properties?.Pages?
                                           .Select(i => i.WebPageGuid)
                                           .ToList();

// Prepares a query that retrieves article pages matching the selected GUIDs
var pageQuery = new ContentItemQueryBuilder()
                    .ForContentType("Acme.Article", config => config
                        .WithLinkedItems(1)
                        .ForWebsite("MyWebsiteChannel")
                        .Where(where => where.WhereIn(nameof(IWebPageContentQueryDataContainer.WebPageItemGUID),  pageGuids)));

// Retrieves the data of the selected article pages
IEnumerable<string> articlePaths = (await executor.GetMappedWebPageResult<Article>(pageQuery))
                                                  .Select(t => t.SystemFields.WebPageItemTreePath);

Attachment selector

There are no plans to make the attachment selector available for Xperience by Kentico. Page attachments are not supported by the system – use Content hub instead.