Customize Xperience by Kentico UI – Channel specific settings

The latest release of Xperience by Kentico introduces numerous new features and simplifies the customization process. However, one notable element from earlier versions that is still missing is the Settings application. This application was particularly valuable as it allowed for the creation and management of site-specific settings, which could be customized according to the needs of different sites. Despite its absence in the current version, we have identified an effective workaround to facilitate a smoother experience with the new Xperience platform. Our solution helps bridge the gap left by the missing Settings application and enhances the ease of working with Xperience's latest features.

This blog post outlines one approach to implementing custom settings in Xperience by Kentico, serving as a foundational guide for further development and customization tailored to your specific needs. While this example focuses on configuring settings for the website channel, the principles discussed can be adapted to other types of channels provided by Kentico. We will cover the key points of the implementation to provide a clear starting point. For a comprehensive guide and detailed instructions on integrating this solution into your own project, please refer to our GitHub repository: Xperience UI Custom Settings.

In line with the new Xperience by Kentico features, we'll begin by creating a custom module. This module will serve the primary purpose of storing the values for defined settings keys, as illustrated in the image below. It will consist of four basic text fields without any validation. The ChannelCustomSettingsChannelID field will represent and reference a Channel object. Ensure that the Code name column is left empty on the code tab to facilitate the addition of multiple copies of the settings key for each channel.

Once the code files have been generated, the next step is to define the settings model that will be used to store data. This model, named ChannelCustomSettingsViewModel, will be utilized to reference the model that should be rendered as a form on the custom edit page. In addition to this, the ChannelCustomSettingsViewModel will serve as the entry point for adding new settings keys for all channels. You can find a sample of the settings model below.

As demonstrated in the code sample above, we have introduced an additional attribute, XperienceSettingsData. This attribute is designed to specify the name under which the setting will be saved, along with the default value to be initialized. The inclusion of XperienceSettingsData allows for greater flexibility in naming your settings keys, effectively bypassing the limitations imposed by C#. This model acts as the foundation for adding all future settings keys. To incorporate a new setting, simply add a new property to the model and decorate it with the appropriate FormComponent and XperienceSettingsData attributes. This approach ensures that the setting becomes visible on the form and available for use.

The final integration takes place in the ChannelCustomSettingsExtender, which registers this feature as a standard Kentico ChannelEditSection. This registration enables the custom settings to appear within the existing channel settings interface, as illustrated below.

The integration is accomplished by applying the UIPage attribute to the ChannelCustomSettingsExtender. This attribute binds the extender to the existing channel section, enabling our custom settings to appear within the standard channel settings interface:

This page extender encapsulates all the logic required to display and store the settings keys on the custom page, including UI configurations to enhance its appearance. The core functionality relies on the ProcessFormData command, which reads data from the settings model and stores it in a flat structure in the database. Each setting is saved with a human-friendly key name and its corresponding value. The reverse process occurs on form load: data is fetched from the database for the specific channel, identified by the ObjectId URL parameter, using the keys defined in the settings model. Please note that these settings are currently restricted to the website channel. Consequently, attempting to access them from other channels, such as the marketing channel, will result in an unsupported message, as illustrated below.

In this implementation, we support only string, integer, and boolean data types. However, you can easily customize and extend this solution to accommodate additional types as needed. To retrieve new settings keys, you can use the IChannelCustomSettingsRepository, which was previously registered in Dependency Injection (DI). This repository simplifies fetching settings by name and automatically resolves the current channel to retrieve the appropriate settings, as demonstrated below.

Please note that this project serves as a showcase and is intended to demonstrate the capabilities of the new Xperience. It should be used as a sample to visualize potential implementations rather than a complete, production-ready solution. We recommend implementing caching to optimize performance when retrieving settings keys on a live site, as the current repository example does not include this feature. Feel free to customize and enhance the repository according to your specific needs. The goal of this blog is to inspire and illustrate how you can leverage and customize the new Xperience. We hope it provides valuable insights and ideas for your own projects.

For detailed instructions on setting up this solution in your project, please refer to the README file available at the following link: Xperience UI Custom Settings GitHub Repository.