Reference

URL Mapping provides a configuration mechanism. We describe how it works in this section.

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.

Here is a comprehensive example of a snippet to put in xwiki.properties:

# The prefix to use for myhandler. Assuming a /xwiki context, requests to /xwiki/myprefix/XXX will be sent to this handler.
# Without a prefix, myhandler will not be active
urlmapping.prefixhandlers.myhandler.prefix=myprefix

# Display a redirection screen for the following number of seconds.
# Special values:
#   0  (the default) skips the redirection screen altogether
#  -1  disables automatic redirections, users will have to click the target link themselves
urlmapping.prefixhandlers.myhandler.delay=0

# 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.
urlmapping.prefixhandlers.myhandler.introMessage=Redirecting. Please update your bookmarks.

# 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.
urlmapping.prefixhandlers.myhandler.notFoundIntroMessage=Sorry, we could not find what you are looking for.

# If set and non-empty, the following will be used as a title in the redirection screen instead of the default, generic one.
urlmapping.prefixhandlers.myhandler.title=We found your doc!

# If set and non-empty, the following will be used as a title in the redirection screen instead of the default, generic one.
# Note: it is not used in the not found screen.
urlmapping.prefixhandlers.myhandler.title=We found your doc!

# The template to use for the redirect screen. If empty, the one provided with the URL Mapping extension will be used.
urlmapping.prefixhandlers.myhandler.redirectScreenTemplate=mycustomredirectscreen.vm

# 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.
urlmapping.prefixhandlers.myhandler.notFoundScreenTemplate=

# The redirect HTTP status to use. By default, a 302 temporary redirect status will be used.
urlmapping.prefixhandlers.myhandler.redirectHttpStatus=307

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

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:

1. any configuration forced by the implementation (likely unusual);
2. the handler-specific configuration;
3. the default configuration;
4. the configuration suggested by the implementation.

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.