Reference - Admin UI form components

This page lists all form components that are available in new installations of Xperience. For details on how to programmatically configure these components when used in component configuration dialogs, see Editing components

All form component attributes are located in the

  • Kentico.Xperience.Admin.Base.FormAnnotations
  • Kentico.Xperience.Admin.Content.FormAnnotations

namespaces.

Selectors

Content item selector

Field data type: Content items
C# data type: IEnumerable<LinkedContentItem>
Form component attribute: ContentItemSelectorComponent

Enables users to select content items from the content hub.

Returns a collection of LinkedContentItem objects that represent the selected items. Each LinkedContentItem object contains an ItemId property storing the node ID of the selected item.

The content item selector can either offer items of a single content type or multiple content types. The content type mode depends on the constructor parameter specified when adding the attribute:

  • string contentTypeName – the code name of the content type whose items you want to list in the selector. The selector works in single content type mode.

  • Type contentTypeFilter – the System.Type of a class implementing IContentTypesFilter, which specifies the allowed content types. When defining the AllowedContentTypeIdentifiers method of the filter class, use the DataClassInfoProvider API to load and filter content types that you want to allow (see the example below). For optimal performance, implement caching for the retrieved content types. The selector works in multiple content type mode.

Configuration properties

  • AllowContentItemCreation – determines whether the selector displays a button that allows users to create new content items. The default value is true. Creation of new items is only possible when the selector is in single content type mode and if the specified content type does not have the Page feature enabled.

Examples

Assignment in model classes
// Assigns the content item selector as the property's editing component
// Returns a list of linked content items (objects that contain the IDs of selected content items)
// Items with the 'MyCompany.ContentType' content type are available for selection
// Creation of new content items via the selector is not enabled
[ContentItemSelectorComponent("MyCompany.ContentType", AllowContentItemCreation = false), Label = "Linked items"]
public IEnumerable<LinkedContentItem> LinkedItems { get; set; } = new List<LinkedContentItem>();


// Allows selection of items with the content types specified by 'CustomContentTypesFilter'
[ContentItemSelectorComponent(typeof(CustomContentTypesFilter), Label = "Items with text")]
public IEnumerable<LinkedContentItem> LinkedItemsWithTextFields { get; set; } = new List<LinkedContentItem>();
IContentTypesFilter example
using System;
using System.Collections.Generic;
using System.Linq;

using CMS.DataEngine;
using CMS.FormEngine;
using CMS.Helpers;

using Kentico.Xperience.Admin.Base.FormAnnotations;

public class CustomContentTypesFilter : IContentTypesFilter
{
    // Array with the 'Text' and 'Long text' data types for content type fields
    private static readonly string[] textBasedDataTypes =
    {
        FieldDataType.Text, FieldDataType.LongText
    };

	// Returns the Guid identifiers of the allowed content types
    public IEnumerable<Guid> AllowedContentTypeIdentifiers
    {
        get
        {
            return DataClassInfoProvider.GetClasses()
                // Gets data classes representing content types
                .WhereTrue(nameof(DataClassInfo.ClassIsDocumentType))
                .WhereTrue(nameof(DataClassInfo.ClassIsCoupledClass))
                .AsEnumerable()
                // Gets only content types with fields using the 'Text' or 'Long text' data types
                .Where(x => FormHelper.GetFormInfo(x.ClassName, false)
                                        .GetFields(true, false, includeDummyFields: false)
                                        .Any(y => textBasedDataTypes.Contains(y.DataType)))
                // Selects the GUID identifiers of the content types
                .Select(x => ValidationHelper.GetGuid(x[nameof(DataClassInfo.ClassGUID)], Guid.Empty))
                .ToList();
        }
    }
}
Selection retrieval
public class ContentItemSelectorUsage : ViewComponent
{
    private readonly IPageRetriever pageRetriever;

    public ContentItemSelectorUsage(IPageRetriever pageRetriever)
    {
        this.pagesRetriever = pageRetriever;
    }

    public IViewComponentResult Invoke(ComponentViewModel<CustomWidgetProperties> model)
    {
		// Retrieves the node IDs of the selected items from the 'LinkedItems' property
		List<int> selectedIds = model?.Properties?.LinkedItems.Select(i => i.ItemId).ToList();
        
		// Retrieves TreeNode objects (content items) that correspond to the selected node IDs
		List<TreeNode> selectedItems = pageRetriever.Retrieve<TreeNode>(query => query
                                           .WhereIn("NodeID", selectedIds))
                                           .ToList();
		// Custom logic...

        return View("...");
    }
}

Media file selector

Field data type: Media files
C# data type: IEnumerable<AssetRelatedItem>
Form component attribute: AssetSelectorComponent

Enables users to select assets from media libraries.

Returns a collection of AssetRelatedItem objects that contain metadata of the selected files. Use the ForAssets ObjectQuery extension method to convert the IEnumerable<AssetRelatedItem> collection into a collection of MediaFileInfo objects.

using CMS.MediaLibrary;

IEnumerable<MediaFileInfo> assetToMediaFileInfo = 
	new ObjectQuery<MediaFileInfo>().ForAssets(assetCollection).GetEnumerableTypedResult();

Configuration properties

  • MaximumAssets – sets the maximum number of selectable assets. If not specified, the default value is 1 (single file selection).
    • 0 – no limit.
    • n – at most n files can be selected at once.
  • AllowedExtensions – a semicolon-separated list of extensions allowed to be selected. The specified list of extensions must be a subset of extensions allowed for the entire system as configured in the Settings application.

Examples

Assignment in model classes
// Assigns the asset selector as the property's editing component
// 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>();
Selection retrieval
public class AssetSelectorUsage : ViewComponent
{
    private readonly IMediaFileInfoProvider mediaFileInfoProvider;

    public AssetSelectorUsage(IMediaFileInfoProvider mediaFileInfoProvider)
    {
        this.mediaFileInfoProvider = mediaFileInfoProvider;
    }

    public IViewComponentResult Invoke(ComponentViewModel<CustomWidgetProperties> model)
    {
        // Retrieves the selected assets from the properties (of a widget, for example)
        IEnumerable<AssetRelatedItem> images = model?.Properties?.Images;

        // Gets the media files represented by the selected assets 
        IEnumerable<MediaFileInfo> mediaFiles = new ObjectQuery<MediaFileInfo>().ForAssets(images);

        return View("...");
    }
}

Object selector

This form component is currently usable only in Page or Form Builder, and model-based edit pages or listing filter models in the Xperience administration.

C# data type: IEnumerable<ObjectRelatedItem>
Form component attribute: ObjectSelectorComponent

Enables users to select any object types from the Xperience database.

Returns a collection of ObjectRelatedItem objects that represent the selected objects from the Xperience database. Each ObjectRelatedItem object contains an ObjectGuid or ObjectCodeName property (depending on the  IdentifyObjectByGuid property) which contains the identifier of a selected object.

Configuration properties

  • ObjectType – a string identifier that sets the code name of the object type listed in the selector.
  • IdentifyObjectByGuid – a boolean property that indicates whether the returned object contains the GUID identifier of the selected object instead of the code name. By default, the option is disabled ( false ) and the returned object contains the object code name. It is recommended to identify objects by their code names for optimal performance.
  • IncludeGlobalObjects – a boolean property that indicates whether global objects are included in the selection in cases where the selected object type may exist in both site and global scope.
  • WhereConditionProviderType – a custom type that allows you to filter what data is available in the object selector using a custom Where condition. The specified condition class must implement the IObjectSelectorWhereConditionProvider interface and define its Get method. The Get method specifies the where condition applied to the data before the list of objects is shown to users.
  • OrderBy – Defines a list of columns by which the data should be sorted, e.g., ["NodeLevel", "DocumentName DESC"]
  • MaximumItems – sets the maximum number of selectable items (objects). If not specified, the default value is 1 (single object selection).
    • 0 – no limit.
    • n – at most n objects can be selected at once.
  • Placeholder – a string property that sets the placeholder text displayed before selecting any items.

Example

Assignment in model classes
[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 objects
    public WhereCondition Get() => new WhereCondition().WhereStartsWith("UserName", "a");

}
Selection retrieval
public class ObjectSelectorUsage : ViewComponent
{
    private readonly IUserInfoProvider userInfoProvider;

    public ObjectSelectorUsage(IUserInfoProvider userInfoProvider)
    {
        this.userInfoProvider = userInfoProvider;
    }

    public IViewComponentResult Invoke(ComponentViewModel<CustomWidgetProperties> model)
    {
        // Retrieves the guid of the selected user from the properties
        Guid guid = model?.Properties?.Users?.FirstOrDefault()?.ObjectGuid ?? Guid.Empty;
        // Retrieves the corresponding user object
        var user = userInfoProvider.Get(guid);

        // Custom logic...

        return View("...");
    }
}

Object selector variants

In addition to the general object selector component, the system provides variant implementations for specific scenarios. See the following table for details:

SelectorComponent attributeDescription

Object code name selector

None, assignable only via the field editor.Returns object code names directly instead of ObjectRelatedItem instances.
Object GUID selectorObjectGuidSelectorComponentReturns object GUIDs directly instead of ObjectRelatedItem  instances.

Page selector

Field data type: Pages
C# data type: IEnumerable<PageRelatedItem>
Form component attribute: PageSelectorComponent

Enables users to select pages from the content tree.

Returns a collection of PageRelatedItem objects that represent the selected pages from the content tree. Each PageRelatedItem object contains a NodeGuid property with the GUID of a selected page.

Configuration properties

  • RootPath – limits the selection of pages to a subtree rooted at a page identified by its node alias path (e.g. "/Products/Coffee-grinders"). Only the specified page and its sub-pages can be selected. If not configured, users can select from the entire content tree.
  • MaximumPages – sets the maximum number of selectable pages. If not specified, the default value is 1 (single page selection).
    • 0 – no limit.
    • n – at most n pages can be selected at once.
  • Sortable – a boolean property that enables the sorting of selected pages.
  • ItemModifierType – a class that implements the IPagePanelItemModifier interface. Provides logic that allows you to disable individual pages offered by the selector based on some custom condition. See the example for usage.

Example

Assignment in model classes
// Assigns the page selector as the property's editing component
// Returns a list of page selector items (node GUIDs)
[PageSelectorComponent(RootPath = "/Articles", MaximumPages = 5, ItemModifierType = typeof(PagesWithUrlPagePanelItemModifier))]
public IEnumerable<PageRelatedItem> Pages { get; set; } = Enumerable.Empty<PageRelatedItem>();
ItemModiferType example
public class PagesWithUrlPagePanelItemModifier : IPagePanelItemModifier
{
    public PagePanelItem Modify(PagePanelItem pagePanelItem, TreeNode page)
    {
		// Disables pages that do not have URLs (their page type's URL feature is disabled)
        pagePanelItem.SelectableOption.Selectable = page.HasUrl();
        pagePanelItem.SelectableOption.UnselectableReason = "This page is not accessible under a URL";
        return pagePanelItem;
    }
}
Selection retrieval
public class PageSelectorUsage : ViewComponent
{
    private readonly IPageRetriever pageRetriever;

    public PageSelectorUsage(IPageRetriever pageRetriever)
    {
        this.pagesRetriever = pageRetriever;
    }

    public IViewComponentResult Invoke(ComponentViewModel<CustomWidgetProperties> model)
    {
        // Retrieves the node GUIDs of the selected pages from the 'Pages' property
        List<Guid> selectedPageGuids = model?.Properties?.Pages?
                                                         .Select(i => i.NodeGuid)
                                                         .ToList();

        // Retrieves the pages that correspond to the selected GUIDs
        List<TreeNode> pages = pageRetriever.Retrieve<TreeNode>(query => query
                                             .WhereIn("NodeGUID", selectedPageGuids))
                                             .ToList();

        // Custom logic...

        return View("...");
    }
}

URL selector

This form component is currently usable only in Page or Form Builder, and model-based edit pages or listing filter models in the Xperience administration.

C# data type: string
Form component attribute: UrlSelectorComponent

Allows content editors to insert a URL to an external resource or select a page from the content tree.

Example

Assignment in model classes
// Assigns the URL selector as the property's editing component
// Returns a string containing the relative URL of the selected page
[UrlSelectorComponent(Label = "Select a page")]
public string PageUrl { get; set; }
Selection retrieval
public class UrlSelectorUsage : ViewComponent
{
    private readonly IUserInfoProvider userInfoProvider;

    public UrlSelectorUsage(IUserInfoProvider userInfoProvider)
    {
        this.userInfoProvider = userInfoProvider;
    }

    public IViewComponentResult Invoke(ComponentViewModel<CustomWidgetProperties> model)
    {
        // Retrieves the selected page url from the properties (of a widget properties class, for example)
        string pageUrl = model?.Properties?.PageUrl ?? String.Empty;

        // Custom logic...

        return View("...");
    }
}

General selector

This form component is currently usable only in Page or Form Builder, and model-based edit pages or listing filter models in the Xperience administration.

C# data type: IEnumerable<string>
Form component attribute: GeneralSelectorComponent

Allows users to select one or more items using a drop-down menu with a search bar. The items offered by the selector can be of any type, including external data outside of Xperience. Developers need to implement a data provider that loads and prepares the items displayed in the selector.

The selector returns a collection of string objects, which contain the values of the selected items.

Configuration properties

  • MaximumItems – sets the maximum number of selected items. If not specified, the default value is 0, which means the number of selected items is not limited.

    Single general selector

    If you only wish to allow selection of a single item, you can use the SingleGeneralSelectorComponent form component attribute instead. The single general selector works just like the general selector, but the returned data type is string and the MaximumItems configuration property is not available.

  • Placeholder – text displayed before an option is selected. E.g., "Choose an option"
  • DataProviderType – dynamic data source for the selector's options.

The general selector's data source class must implement the IGeneralSelectorDataProvider interface and define the following methods:

  • GetItemsAsync – provides the items available in the selector. The searchTerm parameter contains the text entered into the search box (empty when the selector is initially opened). The pageIndex parameter allows you to implement pagination for better performance when working with a very large number of items. To disable pagination, ignore the pageIndex parameter and set the NextPageAvailable property of the return object to false. The method must return a PagedSelectListItems<string> object, containing the selector's options in its Items property, as an IEnumerable<ObjectSelectorListItem<string>> collection.

  • GetSelectedItemsAsync – identifies which items are currently selected. Transforms an IEnumerable<string> collection with the values of the selected items into ObjectSelectorListItem<string> objects, which contain both the item values and the text displayed in the selector interface.

Performance considerations

If you wish to load and display a very large number of items in the general selector, we recommend using pagination and implementing caching in your data provider implementation.

Assignment in model classes
// 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; }
Data provider class
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;

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

using CMS.Membership;

public class UserGeneralSelectorDataProvider : IGeneralSelectorDataProvider
{
    private readonly IUserInfoProvider userInfoProvider;
    private IEnumerable<ObjectSelectorListItem<string>> items;
	// Item representing an invalid selector option
    private static ObjectSelectorListItem<string> InvalidItem => new ObjectSelectorListItem<string>() { IsValid = false };


    public CustomGeneralSelectorDataProvider(IUserInfoProvider userInfoProvider)
    {
        this.userInfoProvider = userInfoProvider;
    } 


    // Returns items displayed in the general selector drop-down list
    public Task<PagedSelectListItems<string>> GetItemsAsync(string searchTerm, int pageIndex, CancellationToken cancellationToken)
    {
        // Prepares a query for retrieving user objects
        var itemQuery = userInfoProvider.Get();

        // If a search term is entered, only loads users users whose first name starts with the term
        if (!string.IsNullOrEmpty(searchTerm))
        {
            itemQuery.WhereStartsWith("FirstName", searchTerm);
        }

        // Ensures paging of items
        itemQuery.Page(pageIndex, 20);

        // Retrieves the users and converts them into ObjectSelectorListItem<string> options
        items = itemQuery.GetEnumerableTypedResult()
                            .Select(x => new ObjectSelectorListItem<string>()
                            {
                                Value = x.UserName,
                                Text = $"{x.FirstName} {x.LastName} ({x.UserName})",
                                IsValid = true
                            });            

        return Task.FromResult(new PagedSelectListItems<string>()
        {
            NextPageAvailable = itemQuery.NextPageAvailable,
            Items = items
        });
    }

	// Returns ObjectSelectorListItem<string> options for all item values that are currently selected
    public Task<IEnumerable<ObjectSelectorListItem<string>>> GetSelectedItemsAsync(IEnumerable<string> selectedValues, CancellationToken cancellationToken) => 
        Task.FromResult(selectedValues?.Select(v => GetSelectedItemByValue(v)) ?? Enumerable.Empty<ObjectSelectorListItem<string>>()
    );

    private ObjectSelectorListItem<string> GetSelectedItemByValue(string value)
    {
        return items.Where(item => (item.Value == value)).First() ?? InvalidItem;
    }
}

Components

Checkbox

Field data type: Boolean (Yes/No)
C# data type: bool
Form component attribute: CheckBoxComponent

Checkbox field that saves a boolean value (true for a selected checkbox, false for a cleared checkbox).

Code editor

Field data type: Text, Long text
C# data type: string
Form component attribute: CodeEditorComponent

Provides a text editing area suitable for code, with support for syntax highlighting and line numbers.

Configuration properties

  • Language – sets the language for the syntax highlighting applied by the editor. The following values are supported:
    • css
    • html
    • javascript
    • sql
    • xml

Dropdown selector

Field data type: Text, Long text
C# data type: string
Form component attribute: DropDownComponent

Drop-down selector offering multiple options. Only one option can be selected.

Configuration properties

  • Options – items must be specified one per line in the format:

    1;One
    2;Two

    When configuring the component using the attribute, the options string must contain newline characters. For example for Windows:

    1;One\r\n2;Two
  • Placeholder – text displayed before an option in the drop-down is selected. E.g., "Month"
  • DataProviderType – dynamic data source for the component. The assigned type must implement the IDropDownOptionsProvider interface.

    Example
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    
    using CMS.Membership;
    
    using Kentico.Xperience.Admin.Base.FormAnnotations;
    
    // Populates the selector with all users from the system
    public class UsersDropdownOptionsProvider : IDropDownOptionsProvider
    {
        private readonly IUserInfoProvider userInfoProvider;
    
        public UsersDropdownOptionsProvider(IUserInfoProvider userInfoProvider)
        {
            this.userInfoProvider = userInfoProvider;
        }
    
        public async Task<IEnumerable<DropDownOptionItem>> GetOptionItems()
        {
            return (await userInfoProvider.Get()
                                          .GetEnumerableTypedResultAsync())
                                          .Select(x => new DropDownOptionItem()
                                          {
                                              Value = x.UserID.ToString(),
                                              Text = x.UserName
                                          });
        }
    }

Date input

Field data type: Date
C# data type: System.DateTime
Form component attribute: DateInputComponent

Date selector.

Remarks

Annotating a non-nullable property results in the input being prepopulated with the minimum selectable date. If you want to display an empty input instead, use the following construction.

[DateInputComponent]
// Use RequiredValidationRule to enforce user input
[RequiredValidationRule]
// Set the property as nullable
public DateTime? Date { get; set; } = null;

DateTime input

Field data type: Date and time
C# data type: System.DateTime
Form component attribute: DateTimeInputComponent

Date and time selector.

Remarks

Annotating a non-nullable property results in the input being prepopulated with the minimum selectable date. If you want to display an empty input instead, use the following construction.

[DateTimeInputComponent]
// Use RequiredValidationRule to enforce user input
[RequiredValidationRule]
// Set the property as nullable
public DateTime? DateAndTime { get; set; } = null;

Decimal number input

Field data type: Decimal number
C# data type: Decimal
Form component attribute: DecimalNumberInputComponent

Input field for entering decimal numbers.

Field data type: Text, Long text
C# data type: string
Form component attribute: LinkComponent

Displays a non-editable link within forms in the administration interface.

Configuration properties

  • Text – the text displayed for the link in the form. If null or empty, the value of the link (the URL) is used instead.
  • OpenInNewTab – a boolean property that indicates whether the link opens in a new browser tab. The default value is true.
  • Inactive – a boolean property that indicates whether the link is disabled and only shown as text. The default value is false.

Number input

Field data type: Integer number
C# data type: Int32
Form component attribute: NumberInputComponent

Text input field for entering whole (integer) numbers.

Password

Field data type: Text, Long text
C# data type: string
Form component attribute: PasswordComponent

Text input field that obscures user input. 

Configuration properties

  • IgnorePasswordPolicy – if set, disregards all password policy configuration when validating input.
  • RequiredLengththe minimum length a password must be. Defaults to 8.
  • RequiredUniqueCharsthe minimum number of unique characters which a password must contain. Defaults to 1.
  • RequireDigita flag indicating if passwords must contain a digit. Defaults to true.
  • RequireNonAlphanumerica flag indicating if passwords must contain a non-alphanumeric character. Defaults to true.
  • RequireUppercasea flag indicating if passwords must contain an upper case ASCII character. Defaults to true.
  • RequireLowercasea flag indicating if passwords must contain a lower case ASCII character. Defaults to true.

Rich text editor

Field data type: Text, Long text
C# data type: string
Form component attribute: RichTextEditorComponent

Allows users to enter HTML-enriched text using the Rich text editor.

Configuration properties

Radio group component

Field data type: Text, Long text
C# data type: string
Form component attribute: RadioGroupComponent

Allows single selection from a group of radio buttons.

Configuration properties

  • Options – specifies each button in the radio group, one per line in the value;label format. For example: 1;One
  • Inline – indicates whether the options are displayed in a horizontal layout on a single line. If false, options are displayed vertically on separate lines.

Text area

Field data type: Text, Long text
C# data type: string
Form component attribute: TextAreaComponent

Allows users to enter text into an area with adjustable size.

Configuration properties

  • CopyButtonVisible – indicates whether a copy that enables users to copy the contents of the text area is visible.
  • MaxRowsNumber – sets the maximum number of rows to which the area expands when text is added. If further rows added, the text area displays a scroll bar.
  • MinRowsNumber – sets the minimum number of rows displayed in the text area (i.e., the area's height).
  • WatermarkText – placeholder displayed when the area is empty.

Text input

Field data type: Text, Long text
C# data type: string
Form component attribute: TextInputComponent

Text input field.

Text with label

Field data type: Text, Long text, Integer number
C# data type: string
Form component attribute: TextWithLabelComponent

Used to display non-editable text together with a label for informational value.

Extension selector

Field data type: Text, Long text
C# data type: string
Form component attribute: ExtensionSelectorComponent

Allows you to specify a list of allowed extensions using a simple interface. Defaults to the list of system-wide allowed extensions specified in the Settings application: ContentMediaMedia file allowed extensions setting. 

Configuration properties

  • AllowedExtensions – the semicolon-delimited list of allowed extensions.