Custom handling of diacritics

The system removes diacritics from text during many parsing operations. For example, diacritics are removed when indexing text for the smart search or when setting page aliases or URL slugs for pages. When the event is triggered, characters with diacritics are replaced by the appropriate base character, for example ü is converted to u.

If you need to change the default behavior of removing diacritics, you can register and implement a handler for the OnBeforeRemoveDiacritics event.

The event is a member of the TextHelper class, which can be found under the CMS.Helpers namespace.

• The handler for this event has 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.
• The handler has 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 a handler for the diacritic removal event:

1. Open your Xperience solution in Visual Studio.

2. Create a custom module class.

   • Add the class into a custom Class Library project within the solution.

3. Override the module’s OnInit method and assign the handler to the required event:

   Copy

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

4. 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.

5. Save the file and Rebuild the solution.

The system applies the changes when removing diacritics from text.