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. Expand the App_Code folder (or CMSApp_AppCode -> Old_App_Code if your project was installed as a web application) and create a new class.

3. Edit the class and add the following references:

   C#

   Copy

   using CMS.Base;
   using CMS.Helpers;

4. Delete the default class declaration and its content. Instead, add the following code:

   C#

   Copy

   [URLFormatHandlerLoader]
   public partial class CMSModuleLoader
   {
       /// <summary>
       /// Custom attribute class.
       /// </summary>
       private class URLFormatHandlerLoaderAttribute : CMSLoaderAttribute
       {
           /// <summary>
           /// Called automatically when the application starts.
           /// </summary>
           public override void Init()
           {
               // 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 and when removing diacritics from text.