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:

• OnBeforeGetSafeUrlPath - 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:

   Copy

   
   
   
    using CMS.Base;
    using CMS.Helpers;
   
   
    

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

   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 OnBeforeGetSafeURLPath event
                URLHelper.OnBeforeGetSafeUrlPath += Custom_OnBeforeGetSafeUrlPath;
   
                // Assigns a handler to the OnBeforeRemoveDiacritics event
                TextHelper.OnBeforeRemoveDiacritics += Custom_OnBeforeRemoveDiacritics;
            }      
   
        }
    }
   
   
    

   This extends the CMSModuleLoader partial class and defines a new attribute. The override the Init method of the CMSLoaderAttribute attribute class allows you to assign custom handlers for events.

5. Add the definition of the Custom_OnBeforeGetSafeUrlPath handler into the private class:

   Copy

   
   
   
    static bool Custom_OnBeforeGetSafeUrlPath(ref string url, string siteName, EventArgs e)
    {
        // Replaces all & characters with the word "and"
        url = url.Replace("&", "and");
   
        // Returns true to indicate that the default URL replacements should also be performed (i.e. removing diacritics and forbidden characters)
        return true;
     }
   
   
    

   This code replaces all ampersand (&) characters with the word and. For example, a page named Products & Services has its default page alias generated as Products-and-Services, which is then used in the page’s URL. This example is only meant as a simple demonstration. In real‑world scenarios, the handler can be much more complex, for example when mapping the character set of an international language to appropriate ASCII characters or words.

   The siteName parameter of the handler contains the code name of the site under which the event occurred. This can be useful if you need to access the forbidden character settings of the given site in your custom code.

6. Add the Custom_OnBeforeRemoveDiacritics handler:

   Copy

   
   
   
    static bool Custom_OnBeforeRemoveDiacritics(ref string text, EventArgs e)
    {           
        // Replaces German special characters
        text = text.Replace( "ä", "ae" );
        text = text.Replace( "ö", "oe" );
        text = text.Replace( "ü", "ue" );
        text = text.Replace( "Ä", "Ae" );
        text = text.Replace( "Ö", "Oe" );
        text = text.Replace( "Ü", "Ue" );
        text = text.Replace( "ß", "ss" );
   
        // Returns true to indicate that the default diacritics removal should also be performed
        return true;                
    }
   
   
    

   This ensures that the system uses custom replacements for German special characters rather than simply stripping the diacritics and leaving the base character.

7. Save the file. Build your project if it was installed as a web application.

The system applies the changes when creating new URLs and when removing diacritics from text.