Create a basic module to hold custom settings

A custom module is a common requirement in digital experience projects. It allows developers to empower certain users to configure the site in new ways that are not available out-of-the-box.

This guide is the first in the series of four and shows how to create a basic custom settings module. The module will hold custom settings keys and values. Administrators and editors with sufficient permissions in the UI will be able to create and adjust the values of these settings, which you can access from your code.

Before you start

This guide requires the following:

• Familiarity with C#, .NET Core, Dependency injection, and the MVC pattern.
• A running instance of Xperience by Kentico, preferably 29.6.1 or higher.
  Some features covered in the Training guides may not work in older versions.

Define module and data class

Create custom module

1. Navigate to your Xperience administration.
2. Create a new module, entering these values:
   • Module name: Project settings
   • Identifiers → Code name: TrainingGuides.ProjectSettings
   Note, that in order to fill out the Code name manually, you need to uncheck the Pre-fill the code name automatically checkbox (checked by default).

   We recommend including your customer’s namespace in the code name (e.g., TrainingGuides.). It will help you easily differentiate the custom modules and their purpose.

Create data class

1. Create new class within your new module. Use the following parameters:

   • Class name: Global settings key
   • Namespace: TrainingGuides
   • Name: GlobalSettingsKey

   Now if you check the CMS_Class table of the database, you’ll see a row representing your new class.

2. Specify Database columns for the class. Add columns with the following properties:

   1. The value of the setting, which you will access in code and used to influence functionality
      • Field name: GlobalSettingsKeyValue
      • Data type: Text
      • Size: 1000
      • Required: True (Enabled)
   2. The code name of the setting, which you will use to find the setting and its value
      • Field name: GlobalSettingsKeyName
      • Data type: Text
      • Size: 200
      • Required: True (Enabled)
   3. The display name of the setting, which provides a human-readable name for the listing page
      • Field name: GlobalSettingsKeyDisplayName
      • Data type: Text
      • Size: 200
      • Required: True (Enabled)
   4. A note field, which tells editors how to use the setting and provides additional context
      • Field name: GlobalSettingsKeyNote
      • Data type: Text
      • Size: 2000
      • Required: True (Enabled)

   

   Column roles designations

   Create fields whose names end in DisplayName, Name, and LastModified with appropriate data types to automatically map them to the Display name column, Code name column, and “Last modified” column roles, respectively.

   Binary and Guid fields will automatically map to the GUID column and Binary column of the class.

   These settings are important for code generation, which we will discuss later in this guide.

   Switch to the Code tab to see that your new fields have been automatically mapped:

   

   Note that you can always manually change the designations on the Code.

Add a UI form for the class

To enable editors or administrators to create items of your class in the admin UI, you need a UI form.

1. Create a new edit form for your class:
   1. UI form name: Global settings key edit
   2. Identifiers → Code name: GlobalSettingsKeyEdit
      In this case, you can simply leave Pre-fill code name automatically checked instead of typing the code name manually. The system-generated code name will be identical.

2. Switch to the Fields tab in the left menu.
3. Add a new UI field for each of your class database fields:
   1. Click New field.
   2. Select a database column you want to map the field to. The available columns are sorted alphabetically.
   3. Fill out field settings as desired and hit Save.
   For our example, let’s set the fields up as follows:
   • GlobalSettingsKeyDisplayName
     • Field caption: Display name
     • Enabled: True (Enabled)
     • Form component: Text input
   • GlobalSettingsKeyName
     • Field caption: Settings key code name
     • Enabled: True (Enabled)
     • Form component: Text input
   • GlobalSettingsKeyValue
     • Field caption: Value
     • Enabled: True (Enabled)
     • Form component: Text area
     • Minimum number of rows: 3
     • Maximum number of rows: 5
   • GlobalSettingsKeyNote
     • Field caption: Notes
     • Tooltip text: Explain the purpose of this settings key.
     • Enabled: True (Enabled)
     • Form component: Text area
     • Minimum number of rows: 3
     • Maximum number of rows: 15

Your custom class and edit form are now ready.

Generate code files

The next step toward accessing your class and its objects in your code in a strongly typed manner is to generate code files for it.

If you are working in the Training guides repository, you can use the following command. (Skip the --exclude parameter if your code doesn’t include the CookieLevelConsentMapping class.)

dotnet run --no-build -- --kxp-codegen --type "Classes" --location "../TrainingGuides.Entities/{type}/{name}/ " --exclude "trainingguides.cookielevelconsentmapping" --with-provider-class "false"

As a result, the system will generate a partial GlobalSettingsKeyInfo class under the namespace matching the module name (TrainingGuides.ProjectSettings) inside the TrainingGuides.Entities project.

Enable CI for the new class

If your project uses Continuous integration, you need to enable the feature for the newly generated GlobalSettingsKeyInfo class. You can achieve this by overriding the object type configuration of the class.

In the TrainingGuides.Entities/Classes/Overrides folder create a partial GlobalSettingsKeyInfo class and override its TYPEINFO definition:

namespace TrainingGuides.ProjectSettings;

public partial class GlobalSettingsKeyInfo
{
    static GlobalSettingsKeyInfo()
    {
        TYPEINFO.ContinuousIntegrationSettings.Enabled = true;
    }
}

Build the module UI

You have created a custom module and class representing custom settings. However, at this point, administrators or editors still cannot manage the settings from the administration dashboard.

Let’s develop some UI pages for them.

The pages will have the following structure in the UI tree:

• Under the Configuration category, we will have a Project settings application.
• Under the application, there will be a listing of Global settings.
• From the Global settings page, the user can:
  • edit a specific setting - through the Edit section holding an Edit global settings key page.
  • create a new setting - through the Create global settings key page.

Create the application page

1. In your source code, navigate to your administration customization project (e.g., TrainingGuides.Admin).

2. Create the following folder structure: Pages/ProjectSettings.

   We recommend matching the folder name with the name of your custom module.

3. In the ProjectSettings folder, create a new class file, ProjectSettingsApplication.cs.

4. Implement your custom UI application page:

using Kentico.Xperience.Admin.Base;
using Kentico.Xperience.Admin.Base.UIPages;
using TrainingGuides.Admin.ProjectSettings;

// Register the UI application pages - see a links and more details in the info box below.
[assembly: UIApplication(
    identifier: ProjectSettingsApplication.IDENTIFIER,
    type: typeof(ProjectSettingsApplication),
    slug: "project-settings",
    name: "Project settings",
    category: BaseApplicationCategories.CONFIGURATION,
    icon: Icons.BoxCogwheel,
    templateName: TemplateNames.SECTION_LAYOUT)]

namespace TrainingGuides.Admin.ProjectSettings;

// The class must inherit from the ApplicationPage base class.
public class ProjectSettingsApplication : ApplicationPage
{
    public const string IDENTIFIER = "TrainingGuides.ProjectSettingsApplication";
}

Permissions

Each application in the Xperience administration needs to declare the set of permissions it actively evaluates.

Our custom module will support viewing, creating, deleting and updating instances of the GlobalSettingsKey class. Let’s add the default system permissions, VIEW, CREATE, DELETE and UPDATE, by decorating the ProjectSettingsApplication class with the UIPermission attributes.

Later on you can further restrict actions (page commands) or UI pages access within the application, using any permission from this set.

...
using CMS.Membership;
...
[UIPermission(SystemPermissions.VIEW)]
[UIPermission(SystemPermissions.CREATE)]
[UIPermission(SystemPermissions.DELETE)]
[UIPermission(SystemPermissions.UPDATE)]
public class ProjectSettingsApplication : ApplicationPage
...

Now if you run your solution, you should be able to see your new Project settings application in the Xperience administration under Configuration.

Define the listing page

Your application is now accessible in the Xperience administration, but if you open it, you will see an empty page right now.

Instead, we want to show a list of available project settings, with an option to perform basic CRUD operations (for the users with sufficient permissions).

Let’s create a listing page and its underlying edit and create pages.

1. Create a ProjectSettings/GlobalSettings folder - let’s keep all our GlobalSettingsKey-related pages in one place.
2. In the GlobalSettings folder, create a new class file, GlobalSettingsListingPage.cs.
3. Implement a UI page using the Listing UI page template.

   • Register the page as a child of ProjectSettingsApplication created in the previous section.

   • Utilize the ASP .NET Core IStringLocalizer and Shared resources to localize the UI labels.

     Read more about this recommended practice in our guide on multilingual in Xperience.

     Note that you need to set up the Shared resources file for each project separately. See an example in our Training guides repository.

   • Decorate the Delete method override with the PageCommand attribute to restrict the action to users with permission to delete.

     Learn more about page commands and permissions in our documentation.
   C#

   GlobalSettingsListingPage.cs

   Copy

   
   using Kentico.Xperience.Admin.Base;
   using TrainingGuides.ProjectSettings;
   using TrainingGuides.Admin.ProjectSettings;
   using TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   using CMS.Membership;
   using Microsoft.Extensions.Localization;
   
   [assembly: UIPage(
       parentType: typeof(ProjectSettingsApplication),
       slug: "global-settings",
       uiPageType: typeof(GlobalSettingsListingPage),
       name: "Global settings",
       templateName: TemplateNames.LISTING,
       order: 0)]
   
   namespace TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   // The class has to inherit from ListingPage.
   public class GlobalSettingsListingPage : ListingPage
   {
       private readonly IStringLocalizer<SharedResources> stringLocalizer;
       protected override string ObjectType => GlobalSettingsKeyInfo.OBJECT_TYPE;
   
       public GlobalSettingsListingPage(IStringLocalizer<SharedResources> stringLocalizer) : base()
       {
           this.stringLocalizer = stringLocalizer;
       }
   
       public override async Task ConfigurePage()
       {
           // Determine which columns of your GlobalSettingsKeyInfo objects to show the user in the list view.
           PageConfiguration.ColumnConfigurations
                       .AddColumn(nameof(GlobalSettingsKeyInfo.GlobalSettingsKeyDisplayName), stringLocalizer["Name"])
                       .AddColumn(nameof(GlobalSettingsKeyInfo.GlobalSettingsKeyValue), stringLocalizer["Value"])
                       .AddColumn(nameof(GlobalSettingsKeyInfo.GlobalSettingsKeyNote), stringLocalizer["Note"])
                       .AddColumn(nameof(GlobalSettingsKeyInfo.GlobalSettingsKeyName), stringLocalizer["Codename"]);
   
           // Add a "New settings" button at the top. This will navigate the user to a "create" page.
           // We will define it in the next section.
           PageConfiguration.HeaderActions.AddLink<GlobalSettingsCreatePage>(stringLocalizer["New setting"]);
   
           // Add an "Edit" row action. This will navigate the user to a "edit" section for a specific instance of GlobalSettingsKeyInfo object.
           // We will define it in the next section.
           PageConfiguration.AddEditRowAction<GlobalSettingsEditSection>();
   
           // Define a "Delete" action for the user with sufficient permissions to remove an existing setting.
           PageConfiguration.TableActions
               .AddDeleteAction(nameof(Delete));
   
           await base.ConfigurePage();
       }
   
       // Ensure only a user with permissions to delete can perform the delete action.
       [PageCommand(Permission = SystemPermissions.DELETE)]
       public override Task<ICommandResponse<RowActionResult>> Delete(int id) => base.Delete(id);
   }
   

Define create and edit pages

Both create and edit pages for GlobalSettingsKeyInfo objects will utilize the GlobalSettingsKeyEdit UI form you created earlier in this guide.

Edit page

When the user goes to edit a specific instance of the GlobalSettingsKey class, their URL should contain the ID of the object that the user is currently editing, e.g., ~/admin/project-settings/global-settings/2/edit

We first need to create an edit section page to ensure a desired tree structure and correct routing. Subsequently, we will make the edit page a child of the edit section page.

1. In the GlobalSettings folder, create a new class file, GlobalSettingsEditSection.cs.

2. Implement the GlobalSettingsEditSection class, utilizing the PARAMETERIZED_SLUG parameter.

   C#

   GlobalSettingsEditSection.cs

   Copy

   
   using Kentico.Xperience.Admin.Base;
   using TrainingGuides.ProjectSettings;
   using TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   
   // Register the UI page as child of GlobalSettingsListingPage.
   [assembly: UIPage(
       parentType: typeof(GlobalSettingsListingPage),
       slug: PageParameterConstants.PARAMETERIZED_SLUG,
       uiPageType: typeof(GlobalSettingsEditSection),
       name: "Edit",
       templateName: TemplateNames.SECTION_LAYOUT,
       order: 10)]
   
   namespace TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   
   // Inherit from EditSectionPage and specify the type of object edited
   public class GlobalSettingsEditSection : EditSectionPage<GlobalSettingsKeyInfo>
   { }
   

3. In the GlobalSettings folder, create a new class file, GlobalSettingsEditPage.cs.

4. Implement your edit page:

   C#

   GlobalSettingsEditPage.cs

   Copy

   
   using Kentico.Xperience.Admin.Base;
   using TrainingGuides.ProjectSettings;
   using TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   using Kentico.Xperience.Admin.Base.Forms;
   
   // Register page as a child of GlobalSettingsEditSection
   [assembly: UIPage(
       parentType: typeof(GlobalSettingsEditSection),
       slug: "edit",
       uiPageType: typeof(GlobalSettingsEditPage),
       name: "Edit global settings key",
       templateName: TemplateNames.EDIT,
       order: 0)]
   
   namespace TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   
   public class GlobalSettingsEditPage : InfoEditPage<GlobalSettingsKeyInfo>
   {
       [PageParameter(typeof(IntPageModelBinder))]
       public override int ObjectId { get; set; }
   
       public GlobalSettingsEditPage(IFormComponentMapper formComponentMapper,
           IFormDataBinder formDataBinder)
           : base(formComponentMapper, formDataBinder)
       {
       }
   
       public override Task ConfigurePage()
       {
           // Assign your 'GlobalSettingsKeyEdit' UI form code name to the page. The assignment is case-insensitive.
           PageConfiguration.UIFormName = "globalsettingskeyedit";
           return base.ConfigurePage();
       }
   }
   

Create page

1. In the GlobalSettings folder, create a new class file, GlobalSettingsCreatePage.cs.

2. Implement the page using the CreatePage base class.

   C#

   GlobalSettingsCreatePage.cs

   Copy

   
   using Kentico.Xperience.Admin.Base;
   using TrainingGuides.ProjectSettings;
   using TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   using Kentico.Xperience.Admin.Base.Forms;
   
   // Register page as a child of GlobalSettingsListingPage created above.
   [assembly: UIPage(
       parentType: typeof(GlobalSettingsListingPage),
       slug: "create",
       uiPageType: typeof(GlobalSettingsCreatePage),
       name: "Create global settings key",
       templateName: TemplateNames.EDIT,
       order: 20)]
   
   namespace TrainingGuides.Admin.ProjectSettings.GlobalSettings;
   
   // Specify the entity which this page will create (GlobalSettingsKeyInfo)
   // and the page to redirect to after the entity has been cerated (GlobalSettingsEdit page)
   public class GlobalSettingsCreatePage : CreatePage<GlobalSettingsKeyInfo, GlobalSettingsEditPage>
   {
       public GlobalSettingsCreatePage(IFormComponentMapper formComponentMapper,
           IFormDataBinder formDataBinder,
           IPageUrlGenerator pageUrlGenerator)
           : base(formComponentMapper, formDataBinder, pageUrlGenerator)
       {
       }
   
       public override Task ConfigurePage()
       {
           // Assign your 'GlobalSettingsKeyEdit' UI form code name to the page. The assignment is case-insensitive.
           PageConfiguration.UIFormName = "globalsettingskeyedit";
           return base.ConfigurePage();
       }
   }
   

Build your solution and navigate to System → UI tree in the Xperience administration. If you have followed along with the example in this guide, you should be able to see your new pages in a UI tree structure:

When you navigate to your new Project settings application, you should now be able to create, view, edit, and delete custom settings, like in this video:

Next steps

You have learned how to create a custom key-value settings module in Xperience. The next guide in this series will demonstrate how you can access your custom settings instances through the ObjectQuery API and work with them in your code.