Page Naming Strategies API

Last modified by Simon Urli on 2020/06/25 06:50

cogA set of APIs to define the name strategies of the wiki entities
Developed by

XWiki Development Team

0 Votes
LicenseGNU General Public License 1
Bundled With

XWiki Standard


Provides APIs to allow performing checks and transformations on page names. The primary intents of this module is to allow admin to have more capabilities to handle the type of pages names that are allowed in their wiki.

Note that this module won't transform automatically all the existing page names once activated: it only performs checks when saving documents after it is enabled.


The Name Strategies can be configured from the Administration Application, on the Editing tab.

Current Naming Strategy


You can select there which name strategy you want to use for the whole wiki.
The different strategies available in XWiki are detailed in the dedicated section.
Note that if you don't want to use any strategy, you can just disable the two following values to not use transformation or validation.
By default the Character Replacement Strategy is selected.

Transform Names Automatically


This option allows you to automatically transform the page names before they are created, in order to comply with the selected strategy.
Note that only the page names will be transformed: the page titles will remain untouched.
By default this option is enabled.

Validate Names Before Saving

This option allows you to automatically validate a page name when it is created: if the page is not valid, the user will get an error and will be asked to use another name.
Note that this concerns the whole path of the page: not only its name, but also the name of its parents.
This validation check is only perform when creating new pages, so even if you enable it you should be able to edit existing documents that don't comply with the naming strategy.
Nevertheless, this feature is still experimental, so it is disabled by default.

Test the Strategy you selected


This text input allows you to type any text to check how the name strategy will behave: it will show you if a potential name is valid or not with the currently selected strategy, and how the strategy would transform the names. You don't need to save for performing the tests, so you can easily change the strategy and validate it before saving. 

Existing Strategies


Character Replacement Strategy

This strategy allows you to define characters that are forbidden in a page name, and how to replace them.
For each forbidden character you define, you can specify a specific replacement character. Or you can chose to not specify a replacement character and in that case, forbidden cases will be just removed.

This strategy is selected by default, with "/" (slash) and "\" (backslash) as forbidden characters, without replacements defined for them.

Preformatted Names Strategy

This strategy will normalize your page names to remove any special characters: only the latin alphabet (26 letters) without accents, the numbers and the character "-" (dash) are accepted. The accents are automatically transformed to the closest latin letter, and all other special characters are transformed to dashes, with some clean up to avoid redundant dashes.

Name Strategy Script Service

A script service is available to use name strategy components. It can be accessed with $services.modelvalidation.
You can check the API directly on the source.

Create a Name Strategy Component


A new strategy component can be created by implementing the EntityNameValidation Java class.
A strategy is defined by transformation and validation methods, for both Strings and for EntityReferences. 

Note that you can extend AbstractEntityNameValidation to only define the transformation and validation methods for Strings and reuse them for the EntityReferences, it's an easier way to define a strategy.

Created by Simon Urli on 2020/01/14 15:46

Get Connected