|
|
Custom handling of URL path values |
|
|
|
|
|
Custom handling of URL path values |
|
|
|
|
|
|
Custom handling of URL path values |
|
|
|
|
|
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 document aliases, document 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 the URL format and configuration topic). Characters with diacritics are replaced by the appropriate base character, for example ü is converted to u.
If you need to change this default behavior in any way, you can customize it by registering and implementing a handler for one or both of the events described below:
•OnBeforeGetSafeUrlPath - occurs whenever a potentially unsafe text value is added to a part of a URL, e.g. when the document alias field is saved (or filled automatically based on the document'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 will also be triggered during many text parsing operations that are not directly related to URLs (e.g. when indexing text for the Smart search).
These events are members of the URLHelper and TextHelper classes respectively, which can be found under the CMS.GlobalHelper namespace.
The handlers for these events have the source text included as a string parameter passed by reference, so any changes made to it in the code will be 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.
|
Important!
Returning a false value should only be done if you are sure that your custom handler can take full responsibility for all URL safety or diacritics removal requirements.
Disabling the default system functionality may prevent parts of your website from working correctly, particularly in the case of handlers for the OnBeforeGetSafeUrlPath event. |
The following example demonstrates how you can define handlers for these events.
1. Open your Kentico CMS web project in Visual Studio, expand the App_Code folder (or Old_App_Code if your project was installed as a web application) and create a new class inside it. It may be placed in a sub-folder if you wish.
2. Edit the new class and add the following references:
[C#]
using CMS.SettingsProvider; |
3. Next, delete the default class declaration and its content. Instead, add the following code:
[C#]
[URLFormatHandlerLoader] /// <summary> /// Loader module registration. /// Called automatically when the application starts. /// </summary> public override void Init() { URLHelper.OnBeforeGetSafeUrlPath += new URLHelper.OnBeforeGetSafeUrlPathEventHandler(Custom_OnBeforeGetSafeUrlPath); // Hooks a handler for the OnBeforeRemoveDiacritics event. TextHelper.OnBeforeRemoveDiacritics += new TextHelper.OnBeforeRemoveDiacriticsEventHandler(Custom_OnBeforeRemoveDiacritics); }
} } |
This extends the CMSModuleLoader partial class and defines a new attribute for it. In a private class representing the attribute, you can override the Init method, which is executed automatically when the application starts. The method can then be used to assign custom handlers for the events.
4. Add the definition of the Custom_OnBeforeGetSafeUrlPath handler under the private class according to the code below:
[C#]
static bool Custom_OnBeforeGetSafeUrlPath(ref string url, string siteName, EventArgs e) { |
This code replaces all ampersand (&) characters with the word and. For example, this means that a document named Products & Services would have its default document alias generated as Products-and-Services, which would then be used in its URL. This example is only meant as a simple demonstration. In real‑world scenarios, the handler could be much more complex, e.g. 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.
5. Next, add the Custom_OnBeforeRemoveDiacritics handler as shown below:
[C#]
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 will use custom replacements for German special characters rather than simply stripping the diacritics and leaving the base character.
Save the file. Build your project if it was installed as a web application. The changes will now be applied when creating new URLs and when removing diacritics from text. Please note that this will not automatically change the aliases and URL paths of existing documents until their current value is changed or saved.
