Wiki source code of URL Mapping configuration
Last modified by Raphaël Jakse on 2026/03/24 09:34
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | URL Mapping provides a configuration mechanism. We describe how it works in this section. | ||
| 2 | |||
| 3 | {{warning}} | ||
| 4 | This configuration mechanism is totally optional, it is up to each particular implementation to use it. Administrators should make sure to check the documentation of each implementation they use to see if it uses this configuration mechanism, and check out which name it uses. | ||
| 5 | {{/warning}} | ||
| 6 | |||
| 7 | {{info}} | ||
| 8 | That said, the easiest and recommended way to write an implementation will make use of this configuration mechanism, it should be safe to assume that it will work with any well-behaved implementation. | ||
| 9 | {{/info}} | ||
| 10 | |||
| 11 | Each implementation has a unique name, which you should find in its documentation. In the reminder of this section, we will consider a fictive implementation named ##myhandler##. Replace ##myhandler## with the actual documented name. | ||
| 12 | |||
| 13 | Here is a comprehensive example of a snippet to put in ##xwiki.properties##: | ||
| 14 | |||
| 15 | {{code language="none"}} | ||
| 16 | # The prefix to use for myhandler. Assuming a /xwiki context, requests to /xwiki/myprefix/XXX will be sent to this handler. | ||
| 17 | # Without a prefix, myhandler will not be active | ||
| 18 | urlmapping.prefixhandlers.myhandler.prefix=myprefix | ||
| 19 | |||
| 20 | # Display a redirection screen for the following number of seconds. | ||
| 21 | # Special values: | ||
| 22 | # 0 (the default) skips the redirection screen altogether | ||
| 23 | # -1 disables automatic redirections, users will have to click the target link themselves | ||
| 24 | urlmapping.prefixhandlers.myhandler.delay=0 | ||
| 25 | |||
| 26 | # In the redirection screen, show this message. If left unset or empty, a generic, default message will be shown. This message will be HTML-escaped and displayed as is. There is no need to escape anything and there is no way to use any formatting. | ||
| 27 | urlmapping.prefixhandlers.myhandler.introMessage=Redirecting. Please update your bookmarks. | ||
| 28 | |||
| 29 | # If a URL is understood but the target is not found, the user will be shown the following error message. If left unset or empty, a generic, default error message will be shown. There is no need to escape anything and there is no way to use any formatting. | ||
| 30 | urlmapping.prefixhandlers.myhandler.notFoundIntroMessage=Sorry, we could not find what you are looking for. | ||
| 31 | |||
| 32 | # If set and non-empty, the following will be used as a title in the redirection screen instead of the default, generic one. | ||
| 33 | urlmapping.prefixhandlers.myhandler.title=We found your doc! | ||
| 34 | |||
| 35 | # If set and non-empty, the following will be used as a title in the redirection screen instead of the default, generic one. | ||
| 36 | # Note: it is not used in the not found screen. | ||
| 37 | urlmapping.prefixhandlers.myhandler.title=We found your doc! | ||
| 38 | |||
| 39 | # The template to use for the redirect screen. If empty, the one provided with the URL Mapping extension will be used. | ||
| 40 | urlmapping.prefixhandlers.myhandler.redirectScreenTemplate=mycustomredirectscreen.vm | ||
| 41 | |||
| 42 | # The template to use for the screen displayed when a target is not found. If empty, the one provided with the URL Mapping extension will be used. | ||
| 43 | urlmapping.prefixhandlers.myhandler.notFoundScreenTemplate= | ||
| 44 | |||
| 45 | # The redirect HTTP status to use. By default, a 302 temporary redirect status will be used. | ||
| 46 | urlmapping.prefixhandlers.myhandler.redirectHttpStatus=307 | ||
| 47 | |||
| 48 | {{/code}} | ||
| 49 | |||
| 50 | {{info}} | ||
| 51 | Templates are rendered using ##com.xpn.xwiki.web.Utils#parseTemplate(String, XWikiContext)##, making it possible to load UI and Javascript extensions for a proper rendering of the full XWiki UI. | ||
| 52 | {{/info}} | ||
| 53 | |||
| 54 | {{info}} | ||
| 55 | Custom templates may decide to honor or not honor the other parameters. | ||
| 56 | {{/info}} | ||
| 57 | |||
| 58 | In addition to the handler-specific configuration, it is possible to provide a default configuration which will apply to all handlers. It is possible to use any key that is documented earlier under ##urlmapping.default## (except ##prefix##: no default prefix can be configured as each handler needs its own, unique prefix). | ||
| 59 | |||
| 60 | In addition to the handler-specific configuration and the default configuration, each implementation (handler) can suggest or force configuration values. When fetching the configuration, the URL Mapping will look for a value in this order: | ||
| 61 | |||
| 62 | 1. any configuration forced by the implementation (likely unusual); | ||
| 63 | 1. the handler-specific configuration; | ||
| 64 | 1. the default configuration; | ||
| 65 | 1. the configuration suggested by the implementation. | ||
| 66 | |||
| 67 | This lets developers provide good defaults, administrator to have a fine-grained control over the configuration and developers to force values when anything else would not make sense. |
