Get to know Xperience by Kentico: The Page Selector form component
Tags: kentico, xperience
Published: 2024-06-18 14:19:59

Form Components are a great way of providing some pretty powerful content editing functionality to marketers and editors in Xperience by Kentico.

They enable us web developers to create fields in editing dialogues within the admin UI that, in-turn, provide functionality to marketers for them to enter and select data to display on their website.

This is achieved by programmatically assigning form components to the properties of widgets, sections, page templates, and much more, by using `Form component attributes`.

Xperience by Kentico provides a whole host of form components out-of-the-box, and this is really powerful as it gives us web developers the flexibility to provide different content editing experiences to suit the needs of marketers, who these days, are looking to content manage their marketing channels faster, and more effectively, than ever.

## What is the Page Selector?

One of my favourite form components is the Page Selector, which enables you to provide a method for editors to select pages from the site tree in a website channel.

As a developer, you can then work with the data of those selected pages to provide functionality in custom components. 

## A trip down memory lane...

The Page Selector has been through a number of iterations in-line with Kentico's development of their DXP. Each time, they've added to its capabilities to make the feature more-and-more useful...

### Kentico Xperience 12

The page selector started its journey in Kentico Xperience 12, where it was introduced as a straightforward method for enabling editors to select a single page from the content tree.

![The Page Selector form component in Kentico Xperience 12](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jo2qmuanrdwsg1dabqe2.png)*Kentico Experience 12 Page Selector*

Under this guise, the component returned the `NodeGuid` of the selected page. Its configuration was fairly limited, but it did have a `RootPath` property that allowed you to limit the selection of pages to those that were located in a specific section of the content tree, otherwise the entire tree was available.

### Kentico Xperience 13

In Kentico Xperience 13, Kentico added the ability for marketers to select multiple pages. In addition, they added the `MaximumPages` property that enabled developers to limit the number of pages that could be selected.

![The Page Selector form component in Kentico Xperience 13](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ne71yawfut35fb2a9j2d.png)*Kentico Xperience 13 Page Selector*

This was a great improvement for editing efficency. Imagine you were in the scenario where marketers had to select three pages to populate a widget with call-to-action links, you could now have one form component to select all three pages to link to, instead of having three separate form components, thus reducing clutter in the widget dialog box, and producing a much more streamlined experience.

### Xperience by Kentico

In Xperience by Kentico, the form component was rebuilt from the ground up to work with Kentico's newly redesigned admin UI, which is built in React, sitting on .Net.

![The Page Selector form component in Xpereince by Kentico](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2g2hkb5rvifzf7xw9cfr.png)*Xperience by Kentico Page Selector*

The thing I really like though is that they took the opportunity to add the killer feature of making selected pages sortable by the marketer.

![The Page Selector form component in Xperience by Kentico](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/883hs53nej0csjschdvx.png)

With KX13, you had to select the desired pages in the order in which you wanted them to be displayed. And if you wanted to change the order, you had to deselect all pages, and then reselect them in the order.

Now with Xperience by Kentico, that issue has disappeared, with the addition of the `Sortable` property, which when set to `true`, enables the drag-and-drop handles, illustrated in the above screenshot.

## A practical example

Imagine you are building an Article Cards widget for the page builder, and you'd like marketers to be able to select the articles they want to display in the widget.

Assuming you have content modelled your articles to be pages in the content tree, you can create a property for your widget, and utilise the `WebPageSelectorComponent`, which is the form component attribute you need to use when you want to render the Page Selector for a widget property:

```csharp
using System.Collections.Generic;
using System.Linq;
using CMS.Websites;
using Kentico.PageBuilder.Web.Mvc;
using Kentico.Xperience.Admin.Websites.FormAnnotations;

public class CardWidgetProperties : IWidgetProperties
{
    [WebPageSelectorComponent(
        TreePath  = "/Articles", 
        MaximumPages = 3, 
        Sortable = true, 
        ItemModifierType = typeof(WebPagesWithUrlWebPagePanelItemModifier), 
        Label = "Select pages", 
        Order = 2)]
    public IEnumerable<WebPageRelatedItem> SelectedArticlePages { get; set; } = Enumerable.Empty<WebPageRelatedItem>();
}
```
As you can see, I've added the following configuration properties:

- `TreePath` - so that it only offers up pages that sit within our Article section of the tree. We want to lead marketers to the correct section of the content tree to make their life easier. It wouldn't be a great experience if we just displayed the entire content tree, otherwise as the tree grows in size, it will make it more difficult for them to find the correct section in the tree.
- `MaximumPages` - we've ensured marketers can only select a maximum of 3 pages, as (hypothetically) in this case the design and solution dictate a maximum limit of article cards to be displayed
- `Sortable` - as we'd like marketers to be to control the sort order of the article cards separate for each instance of the widget.
- `ItemModifierType` - lets us set a type that implements the `IWebPagePanelItemModifier` interface, and in this case, we are using the built-in `WebPagesWithUrlWebPagePanelItemModifier` type, which ensure that only pages that have the URL feature enabled are selectable in the content tree. Content-only pages are still displayed, but in a disabled state.

And of course, there are the generic `Label` and `Order` properties for defining the text for the property's label, and the order in which it appears in the widget dialog in relation to other properties.

## In conclusion

The Page Selector is now a very useful, mature tool in the Kentico web developer's arsenal that helps to streamline the editing process for marketers.

- Read [Kentico's Page Selector documentation](https://docs.kentico.com/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components#page-selector)
- View [Kentico extensive list of Admin UI form components](https://docs.kentico.com/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components)