UI page extenders

If you need custom functionality or content adjustments that you cannot configure through the properties available from the admin UI, you can develop a page extender for the corresponding page.

Page extenders allow you to modify the back-end definition of existing UI pages without directly editing their source code. You can use them to add new commands or change the initial configuration of pages. For example, you can add additional columns to an object listing (e.g., to display additional properties of registered users) or specify new actions (e.g., perform a specific operation with selected objects).

The following diagram illustrates the function of page extenders.

Page extender overview diagram

Create page extenders

All page extenders must inherit from the PageExtender<TPage> base class. Substitute the generic parameter with the type of the page you wish to extend.

To find the implementing type of default or other third-party pages that don’t make their source code available, the admin UI provides the UI tree view available in the System application. See Register new pages under existing admin UI pages for more information.

Creating a page extender



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

// Extends the user listing from the 'Users' application
public class UserListExtender : PageExtender<UserList>
{ 
}

Modify the page configuration

Within page extenders, you can modify the default configuration of the page and its client template properties.

The options available to you largely depend on the type of the page you wish to extend. See Reference - UI page templates for a list of templates on which most of the administration interface is built.

Example - extending the Users application user listing page



public class UserListExtender : PageExtender<UserList>
{
    // Configures the listing template on which UserList is based
    // The available configuration options vary based on the type of the extended page
    public override Task ConfigurePage()
    {
        // Adds a new action to each item in the listing
        Page.PageConfiguration.TableActions.AddCommand...

        // Adds a new action for the entire listing
        Page.PageConfiguration.HeaderActions.AddCommand...

        return base.ConfigurePage();
    }

    // Configures the properties of the client template this page is based on
    // Called after the 'ConfigurePage' method
    public override Task<TemplateClientProperties> ConfigureTemplateProperties(TemplateClientProperties properties)
    {
        // Manipulate properties as desired

        return base.ConfigureTemplateProperties(properties);
    }
}

Add new page commands

You can use extenders to add new page commands.

Declare a new method within the page extender class and annotate it with the PageCommand attribute. The process is identical to writing commands for UI pages.



[PageCommand]
public async Task<ICommandResponse> MyExtenderCommand()
{
    // Command logic...

    return Response().AddSuccessMessage("Command executed.");
}

Respond to commands using events

Page extenders expose Before and After events, accessible via the CommandExecute object. The events fire before and after a command is executed on the server.

The event arguments object PageCommandEventArgs gives access to the following properties:

Property	Description
CommandName	Name of the command being handled.
CommandParameters	Parameters with which the command was invoked from the client. See the documentation about page commands for more information.
CommandResponse	Response sent from the server to the client.

Use these events to react to specific commands from the client or add custom handling.

Example – execute custom logic for specific commands



using System;

using CMS.Core;

using Kentico.Xperience.Admin.Base;

// Defines an extender for 'MyPage'
public class MyPageExtender : PageExtender<MyPage>
{
    private readonly IEventLogService eventLogService;

    public MyPageExtender(IEventLogService eventLogService) 
    {
        this.eventLogService = eventLogService;

        AddEventHandlers();
    }

    private void AddEventHandlers()
    {
        CommandExecute.After += LogPageCommandExecution;
    }

    private void LogPageCommandExecution(object sender, PageCommandEventArgs e)
    {
        // Executes only for 'MyCommand' 
        if (String.Equals(e.CommandName, "MyCommand", StringComparison.OrdinalIgnoreCase))
        {
            // Logs information about command execution to the event log
            eventLogService.LogInformation("PAGECOMMAND", "MyCommand executed");

            // Displays an information message in the admin UI
            e.CommandResponse.AddInfoMessage("Execution logged");
        }
    }
}

Register page extenders

Page extenders need to be registered in the system via the PageExtender assembly attribute.

When registering extenders, you need to provide the System.Type of the implementing class.

Page extender registration



using Kentico.Xperience.Admin.Base;

// Registers the page extender of the 'MyPageExtender' type into the system
[assembly: PageExtender(typeof(MyPageExtender))]

public class MyPageExtender : PageExtender<MyPage> 
{
    ...
}