Custom handling of URL path values

To ensure that URLs can be processed correctly, the system checks text values for unsafe characters before they are added to the URL path, and makes any necessary changes. This affects fields such as page aliases, page URL paths, forum names, post subjects etc.

By default, the process includes removal of diacritics and replacement of all forbidden characters according to the settings defined for the given site (as described in URL format and configuration). Characters with diacritics are replaced by the appropriate base character, for example ü is converted to u.

If you need to change the default behavior in any way, you can register and implement a handler for one or both of the following system events:

• OnBeforeGetSafeUrlPart - occurs whenever a potentially unsafe text value is added to a part of a URL, e.g. when the page alias field is saved (or filled automatically based on the page's name). This event can be used to customize the final format of URL paths. For example, you can convert characters from an international character set to an equivalent in Latin characters (ASCII) or specify a unique replacement string for particular forbidden characters.
• OnBeforeRemoveDiacritics - occurs whenever the system removes diacritics from text. This is one of the default steps performed when creating safe URLs, but the event is also triggered during many text parsing operations that are not directly related to URLs (for example when indexing text for the Smart search).

The events are members of the URLHelper and TextHelper classes respectively, which can be found under the CMS.Helpers namespace.

• The handlers for these events have the source text included as a string parameter passed by reference, so any changes that you make in the code are reflected in the result.
• Both handlers have a boolean return value that indicates whether the default functionality should also be performed after the handler is executed. For this reason, it is highly recommended to set the return value to true for all but the most extensive customizations.

Example

The following example demonstrates how to define handlers for the forbidden character events:

1. Open your Kentico web project in Visual Studio.

2. Create a custom module class.

   • Either add the class into a custom project within the Kentico solution (recommended) or directly into the Kentico web project (into a custom folder under the CMSApp project for web application installations, into the App_Code folder for web site installations).

3. Override the module's OnInit method and assign handlers to the required events:

   C#

   Copy

   using System;
   
   using CMS;
   using CMS.DataEngine;
   using CMS.Helpers;
   
   // Registers the custom module into the system
   [assembly: RegisterModule(typeof(CustomURLPathModule))]
   
   public class CustomURLPathModule : Module
   {
       // Module class constructor, the system registers the module under the name "CustomURLPathHandling"
       public CustomURLPathModule()
           : base("CustomURLPathHandling")
       {
       }
   
       // Contains initialization code that is executed when the application starts
       protected override void OnInit()
       {
           base.OnInit();
   
           // Assigns a handler to the OnBeforeGetSafeURLPart event
           URLHelper.OnBeforeGetSafeUrlPart += Custom_OnBeforeGetSafeUrlPart;
   
           // Assigns a handler to the OnBeforeRemoveDiacritics event
           TextHelper.OnBeforeRemoveDiacritics += Custom_OnBeforeRemoveDiacritics;
       }
   }

The system applies the changes when creating new URLs or page aliases, and when removing diacritics from text.