Applying customizations in the Xperience environment

With the Xperience MVC and Core development models, the live site application and administration application each have their own separate code base and project files. You can modify the system’s functionality for both applications using the same customization API and endpoints described throughout the documentation.

However, customization of the administration application does not automatically apply to the live site application and vice versa. For every customization, you need to consider which applications should be affected and deploy your custom code accordingly:

• Both applications – in many cases, customizations need to cover both applications to work consistently. Typical examples are customizations of e-commerce functionality or user-related actions, which can occur both on the live site and through the administration interface. See Deploying custom code to both applications.
• Administration-only – for customizations that modify or extend parts of the administration interface or only affect functionality triggered in the administration. For example, extenders of UI elements or custom scheduled tasks.
• Live site-only – for customizations of actions that only occur on the live site. For example, code that adjusts the contact recognition logic.

Deploying custom code to both applications

We recommend using the following approach to deploy shared custom code to both the live site and administration applications:

1. Add a custom assembly (Class Library project) in one of the applications (under either the live site solution or the Xperience administration WebApp.sln solution).

2. Create classes with the required custom code in the project.

3. Add the same project to the other application’s solution.

   Important: When working with the Xperience administration solution, make sure that you do NOT install the Kentico.Xperience.Libraries package into the CMSApp project. The project already references Xperience DLLs in the solution’s Lib folder.

Having a project in both solutions ensures that changes are shared between the projects during development.

If you also have customizations intended for only one of the applications, we recommend creating a separate Class Library project in each solution. In this scenario, you can share individual code files between the projects by adding them as links in Visual Studio.

Example

The following example demonstrates how to prepare a customization that automatically assigns new users to a default role. Users can be created both in the administration interface and on the live site (registration of visitors), so the customization is deployed to both applications to ensure that it works consistently.

Start by adding the customization to the live site project:

1. Open your live site solution in Visual Studio.

2. Add a custom assembly (Class Library project) with class discovery enabled to the solution, or re-use an existing assembly. For example, name the project Custom.

3. Reference the Custom project from your live site web project.

4. Create a new class under the custom project, for example named CustomUserModule (the example uses an event handler to extend the user functionality):

   Copy

   
   
   
    using CMS;
    using CMS.DataEngine;
    using CMS.Membership;
    using CMS.SiteProvider;
   
    // Registers the custom module into the system
    [assembly: RegisterModule(typeof(Custom.CustomUserModule))]
   
    namespace Custom
    {
        public class CustomUserModule : Module
        {
            // Module class constructor, the system registers the module under the name "CustomUsers"
            public CustomUserModule()
                : base("CustomUsers")
            {
            }
   
            // Contains initialization code that is executed when the application starts
            protected override void OnInit()
            {
                base.OnInit();
   
                // Assigns a handler to the Insert.After event of user objects
                UserInfo.TYPEINFO.Events.Insert.After += User_InsertAfterEventHandler;
            }
   
            // Handler method that runs when a new user object is created in the system
            private void User_InsertAfterEventHandler(object sender, ObjectEventArgs e)
            {
                if (e.Object != null)
                {
                    // Gets an info object representing the new user
                    UserInfo user = (UserInfo)e.Object;
   
                    // Gets the "DefaultRole" role
                    RoleInfo role = RoleInfo.Provider.Get("DefaultRole", SiteContext.CurrentSiteID);
   
                    if (role != null)
                    {
                        // Assigns the role to the user
                        UserInfoProvider.AddUserToRole(user.UserName, role.RoleName, SiteContext.CurrentSiteName);
                    }
                }
            }
        }
    }
   
   
    

5. Save all changes and Rebuild the solution.

Now add the customization to your Xperience administration project:

1. Open your Xperience administration solution in Visual Studio (using the WebApp.sln file).
2. Right-click the solution in the Solution Explorer and select Add -> Existing Project.
3. Navigate to the Custom folder in the web project and select the Custom.csproj file.
4. Click Open.
5. Reference the Custom project from the administration web project (CMSApp).
6. Save all changes and Rebuild the solution.

The customization is now applied to both applications. The shared custom project allows you to keep changes in the custom code synchronized between the applications during development. When a new user registers on the live site or is created manually in the administration interface, they are automatically assigned to the DefaultRole role (you need to create a role with this code name).