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; } = new List<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; } = new List<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; } = new List<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; } = new List<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; } = new List<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

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

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();

// Retrieves the data of the selected article pages
IEnumerable<string> articlePaths = (await contentRetriever.RetrievePagesByGuids<Article>(pageGuids))
                                                  .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.