Prepare your environment for admin development

This page provides information about the requirements and configuration necessary to get started customizing the Xperience administration interface. Find information about:

• Requirements
• Client development boilerplate
  • Naming conventions
  • Boilerplate project overview
  • Add the boilerplate to an Xperience project
  • Choose how to serve client scripts
  • Export custom React components
  • Keep client packages up-to-date
  • Rename the boilerplate project

Requirements

Depending on the scope of your planned customizations, you need some or all of the following components installed on your machine.

To make changes to existing applications and pages (via page extenders), or add new pages and applications based on existing templates, you will only be making changes to the administration back end. For this, you need:

• A development environment with support for .NET (such as Visual Studio)

If the default set of components is insufficient and you need custom UI page templates, form components, validation rules, and other components for your planned customizations, you will be developing JavaScript modules that plug into the front-end React application. For this, you also need: 

• The latest NodeJS LTS version
• A compatible package manager of your choice
• An editor for JavaScript development with TypeScript support (such as Visual Studio Code)
• Boilerplate project for the development of client JavaScript modules

Client development boilerplate

Xperience provides a boilerplate project to help you get started writing custom client components for the admin UI. We recommend using the boilerplate to bootstrap your environment. However, using the project is not required. If you are familiar with the way the admin UI consumes custom modules, you can set up a custom process.

The boilerplate project is available as a .NET template as part of the Kentico.Xperience.Templates package. To install it, run the following command in a suitable directory:

dotnet new kentico-xperience-admin-sample -n <project_name>

The project includes:

• a template for developing JavaScript modules for the admin UI with minimum required dependencies and configuration
• a .NET class library project to store back end code and embed the client module
• examples demonstrating customization options

For more information about the contents of the boilerplate project and its default configuration, see Boilerplate project overview.

Naming conventions

JavaScript client modules are registered into the system based on naming conventions that use the organization name and project name. These values can be seen referenced in multiple places throughout the project.

• In webpack.config.js in the client JS module template
• In the .csproj file of the class library containing back-end customizations
• In the Module.cs class file where the client module is registered via RegisterClientModule

These conventions ensure uniqueness when sharing client modules with other Xperience projects.

Boilerplate project overview

The boilerplate project is made up of two main parts:

1. a NodeJS project for developing JavaScript modules
2. a .NET class library project

NodeJS project overview

The project comes with all required dependencies and recommended configuration, allowing you to immediately start development. The following table highlights important files:

.NET class library overview

The class library primarily serves as an entry point for client customizations. Client modules need to be registered before they can be used, which occurs in the following files:

<PropertyGroup>
    <AdminOrgName>organizationName</AdminOrgName>
</PropertyGroup>

<ItemGroup>
    <!-- Output folder of the client build process -->
    <AdminClientPath Include="Client\dist\**">
        <ProjectName>projectName</ProjectName>
    </AdminClientPath>
</ItemGroup>

RegisterClientModule("organizationName", "projectName");

Other files included in the class library demonstrate customization options available for the admin UI. See Admin UI customization model overview.

Add the boilerplate to an Xperience project

Before you can start using the boilerplate to develop client code, you need to add it to your Xperience project:

1. Install the boilerplate project next to your Xperience project’s folder. Requires the Kentico.Xperience.Templates package to be installed.

   Copy

   
   
    dotnet new kentico-xperience-admin-sample -n <project_name>
   
    

   

2. Extract the contents next to your Xperience project’s folder.

3. Reference the boilerplate project from your Xperience project. 

   Copy

   
   
    cd xperience\project\location
    dotnet add reference ..\Acme.Web.Admin\Acme.Web.Admin.csproj
   
    

4. Install all dependencies for client-side development using your package manager and build the package.

   Copy

   
   
    # Switches to the directory containing boilerplate client module code
    cd ..\Acme.Web.Admin\Client
    npm install
    npm run build
   
    

5. Configure the client module in the Xperience web application.

   1. Open appsettings.json of your Xperience project.

   2. Add the module and configure your preferred way of handling client scripts under CMSAdminClientModuleSettings.  

      appsettings.json

      Copy

      
      
       "CMSAdminClientModuleSettings": {
           // Add the module name in the <orgName>-<projectName> format separated by hyphens 
           "acme-web-admin": {
               "Mode": ""
           }
       }
      
       

6. Build the web application project.

Your environment is now ready for the development of admin UI JavaScript modules.

Choose how to serve client scripts

The admin UI customization framework supports multiple methods of accessing client scripts. You set which method to use when configuring the module:

npm run start

"CMSAdminClientModuleSettings": {
    "orgName-projectName": {
        // In Proxy mode, client scripts are built separately and requests for them are proxied to the webpack server
        "Mode": "Proxy",
        // The port number needs to match the port set for the webpack server in webpack.config.js
        "Port": 3009   
    }
}

<PropertyGroup>
<TargetFramework><!-- framework_version --></TargetFramework>
<AdminOrgName>acme</AdminOrgName>
</PropertyGroup>

<ItemGroup>
<AdminClientPath Include="Client\dist\**">
    <ProjectName>web-admin</ProjectName>
</AdminClientPath>
</ItemGroup>

"CMSAdminClientModuleSettings": {
    "orgName-projectName": {
        // In Embedded mode, client scripts are stored in an assembly as embedded resources.
        // Mainly intended for deployment scenarios.
        "Mode": "Embedded"
    }
}

Export custom React components

You must export all components that you want to make available from the main Xperience admin UI application via the custom module’s entry.tsx file. This primarily includes all components covered in the customization section, such as UI pages, UI form components, validation and visibility rules.

// Exposes components from the module.
// The export must declare the full path to the given component file.
export * from './custom-layout/CustomLayoutTemplate';
export * from './form-components/ColorSelectorFormComponent';

Keep client packages up-to-date

When updating your Xperience project, remember to also update the dependencies of your admin UI client project – @kentico/xperience-admin-base, @kentico/xperience-admin-components, @kentico/xperience-webpack-config, etc.

Use the npm-update command:

# Switches to the directory containing boilerplate client module code
cd ..\Acme.Web.Admin\Client
npm update

Rename the boilerplate project

The admin UI customization framework relies on naming conventions to register JavaScript modules. All modules follow the organizationName.projectName naming pattern.

You can set these parameters when creating the boilerplate project. This way the project is created and configured with the correct values.

However, you can always rename the project at a later point by changing specific configuration files and folder names. This guide assumes the following values used during boilerplate creation:

• orgName: Acme
• projectName: Web.Admin

Client code

All files referenced in this section are located under ~/Acme.Web.Admin/Client.

1. Change the orgName and projectName settings in Xperience’s webpack configuration under ~/webpack.config.js. This changes the name of the resulting module built by webpack:

   webpack.config.js

   Copy

   
   
    const baseConfig = (webpackConfigEnvc, argv) => {
        return xperienceBaseWebpackConfig({
            // Change the orgName to your desired value
            orgName: "acme",
            // Change the projectName to your desired value
            projectName: "web-admin",
            webpackConfigEnv: webpackConfigEnv,
            argv: argv
        });
    };
   
    

2. (Optional) Change the name of the JavaScript module in package.json:

   package.json

   Copy

   
   
    {
        name: "acme-web-admin",
        ...
    }
   
    

Back end code

1. Edit the .csproj file of your class library project under ~/Acme.Web.Admin and change the following configuration:

   Acme.Web.Admin.csproj

   Copy

   
   
    <PropertyGroup>
      <TargetFramework><!-- framework_version --></TargetFramework>
      <!-- Change the organization name -->
      <AdminOrgName>acme</AdminOrgName>
    </PropertyGroup>
   
    <ItemGroup>
      <AdminClientPath Include="Client\dist\**">
        <!-- Change the project name -->
        <ProjectName>web-admin</ProjectName>
      </AdminClientPath>
    </ItemGroup>
   
    

2. Edit ~/Acme.Web.Admin/Module.cs and change:

   Module.cs

   Copy

   
   
    public class Module : AdminModule
    {
        // (Optional) Change the name of the custom module
        public Module()
            : base("Acme.Web.Admin")
        {
        }
   
        protected override void OnInit()
        {
            base.OnInit();
   
            // Change the organization name and project name in the client scripts registration
            RegisterClientModule("acme", "web-admin");
        }
    }