Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
Virtual URI mapping is a way to redirect an incoming request to the actual location of the content. Typically, the virtual address does not match the site hierarchy exactly.
Virtual URI mapping is an area where you can quickly break a site if you are not careful. It is easy to create cyclical mappings where the result of one mapping feeds another mapping. This can have unintended consequences and render AdminCentral unreachable. Create and test mappings in an isolated test environment before deploying them to production. If something goes wrong and you cannot access AdminCentral anymore, use the Groovy Rescue App to delete the problematic mapping.
The logic of virtual URI mapping in Magnolia
A given mapping configuration "maps" an incoming URI to a new target URI. It returns a result describing the new URI and the level of match. The following action prefixes are supported for the new URI:
redirect:
permanent:
forward:
to trigger either a temporary redirect, a permanent redirect or a forward, respectively. See the Action prefixes section below for more detailed explanations.
The URIs can be either absolute or relative within the web application in which case the context path is added automatically. For example:
It is important to keep in mind the placement of the virtualURIFilter in the chain. The filter acts on the current URI at the time of execution. Any selectors removed from the current URI before the filter executes cannot be configured in fromUri
. For example, langauge selectors would be removed from the current URI before the filter executes.
- Relative
fromUri: /winter2016
toUri: forward:/marketing/campaigns/winter2016
- Absolute
fromUri: /winter2016
toUri: forward:https://www.example.com/marketing/campaigns/winter2016.html
The mappings registry
The mappings are delegated to a separate module (virtual-uri
) through the info.magnolia.virtualuri.VirtualUriFilter
class and are stored in their own registry (VirtualUriRegistry
), which allows to reference each mapping also in YAML definition files. All virtual URI mappings can be located via the Definitions app no matter whether they come from JCR or a YAML file:
Alternatively, search the config
space with the JCR browser app:
Warnings for overflow events are logged in DirectoryWatcher
. Overflow events happen when the maximum number of user watches is reached.
Any existing buffer size is hard-coded and cannot be configured. We recommend to keep the number of files in a single folder below 100 and to use folder hierarchies whenever possible.
Where to use virtual mappings
Virtual URIs are commonly used in Internet marketing for:
- Campaigns, events, conferences, shows, vanity URLs
- Microsites
- Landing pages, geo or language specific pages
- Product pages
- Conversion pages
- Downloads
- Coupon codes, special offers
- Abbreviations, shorthands
There are also utility reasons for redirecting URLs, related to day-to-day site maintenance:
- Web pages have moved due to site re-organization. Users still have old URLs in their bookmarks and in search engine indexes. Without redirection traffic would be lost.
- Registering alternative domain extensions like
example.net
andexample.org
and redirecting them to your primary siteexample.com
. You can map multiple domain names to a site in your Magnolia site definition. This can be a major time-saver for a CMS team since there is no need to configure a Web server. Note that you need to register the domains with a registrar first and make sure that DNS entries for the domains point to the server hosting your Magnolia instance.
As an example of mapping, see also Turning a template-based JSON provider into a RESTful API with virtualURIMapping where we define a custom virtual mapping to rewrite a path like /getjson/tours/magnolia-travels/Kyoto
into /getjson?workspace=tours&path=/magnolia-travels/Kyoto
.
Configuration
You can create virtual URI mappings in the virtualUriMappings
folder inside your module configuration.
Please note that the YAML-based configuration must be stored under the virtualUriMappings
folder, with the plural
-s
at the end and camel-cased Uri
in the middle of the name of the folder. In JCR configuration, the node's name can be either virtualUriMappings
or the older virtualURIMapping
. In either case make sure that the folder is at the top level inside module configuration.
Via JCR
Example: A mapping named enterprise-edition
forwards users from
example.com/ee
to
example.com/enterprise-edition
. The DefaultVirtualUriMapping
class (for description see the Mapping classes section below) maps one URI to another. This ensures that external links that point to
example.com/ee
still work when the target page is renamed.
Node name | Value |
---|---|
<my-module> | |
virtualUriMappings | |
enterprise-edition | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /ee |
toUri | forward:/enterprise-edition |
Via YAML
You can configure virtual URI mappings in a YAML definition file inside a light module folder:
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping fromUri: /ee toUri: forward:/enterprise-edition
Properties
class | required Class that performs the mapping. See the section Mapping classes below. |
fromUri | required Pattern to match in the requested URI. |
toUri | required Concrete URI where the request is mapped to. |
site | required (for the Specifies the site that should be used for the mapping. |
A catalog of mappings
For easier orientation, if you have to configure a lot of mappings, you can store them in folder-like structures rather than in one long flat list of mappings:
Node name | Value |
---|---|
<my-module> | |
virtualUriMappings | |
europe | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /customer-support-europe.html |
toUri | forward:/europe/cust-support.html |
usa | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /customer-support-usa.html |
toUri | forward:/usa/cust-support.html |
asia-australia | |
asia | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /customer-support-asia.html |
toUri | forward:/asia/cust-support.html |
australia | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /customer-support-australia.html |
toUri |
Mapping classes
Magnolia provides eight ready-made classes that perform virtual URI mapping:
info.magnolia.virtualuri.mapping.*
- DefaultVirtualUriMapping maps a virtual URI to a content path. This is the simplest and most common type.
If the URI starts with a dot (.
), it is not taken as a wildcard anymore but the dot in fact is interpreted as dot. If you need a wildcard, use?
instead. - RegexpVirtualUriMapping allows you to specify a regular expression pattern that matches a sequence of characters. A regexp pattern can match a variety of URIs, which saves time and effort as you would otherwise have to create default mappings for each case.
toUri
can contain back references to the regexp matches. RotatingVirtualUriMapping is an extension of
RegexpVirtualUriMapping
that allows rotation between different destination URIs. In order to rotate,toUri
must contain an asterisk character*
that will be replaced by a random integer betweenstart
(default is 1) andend
minus one (default is3
). An additional propertypadding
specifies the desired width of the string. Zeroes are added to the left of the integer to make all strings equally wide. Default width is2
.- HostBasedVirtualUriMapping forwards the request to a different URI depending on the requested host name.
- HostBasedRegexpVirtualUriMapping combines the host-based and regex mappings, i.e. forwards the request to a different URI depending on the requested host name and allows you to specify a regular expression pattern that matches a sequence of characters.
- DefaultVirtualUriMapping maps a virtual URI to a content path. This is the simplest and most common type.
info.magnolia.module.googlesitemap.config.mapping.*
- SiteMapVirtualUriMapping compares source URI to names of sitemaps available in the
googleSitemaps
workspace and prepends the prefix.
- SiteMapVirtualUriMapping compares source URI to names of sitemaps available in the
info.magnolia.multisite.mapping.*
- MultiSiteRootVirtualUriMapping is a special class which specifies the root of a site if site matching returns
null
. - MultiSiteRegexpVirtualUriMapping adds a site condition to the mapURI check. A mapping will only match the request if both the specified regular expression and the specified site match.
- MultiSiteRootVirtualUriMapping is a special class which specifies the root of a site if site matching returns
You can also write your own implementation.
The patterns for regular expressions in the regex-based classes are defined in java.util.regex.Pattern.
Deprecated classes
The following classes have been deprecated since Magnolia 5.6:
info.magnolia.module.googlesitemap.config.*
- SiteMapVirtualUriMapping
info.magnolia.multisite.*
- MultiSiteRootVirtualURIMapping
- MultiSiteRegexpVirtualURIMapping
Action prefixes
You can use these action prefixes:
forward
hides the true target URL from the visitor. The URL that the user typed in the browser address bar or the link they clicked remains visible. Forward is performed internally by the servlet. Any browser reload of the resulting page will repeat the original request, with the original URL.redirect
displays the true target URL in the address bar. It is a two-step process where the web application instructs the browser to fetch a second URL which differs from the original. A browser reload of the second URL will not repeat the original request but will rather fetch the second URL. Redirect is marginally slower than a forward since it requires two browser requests instead of one. A redirect returns HTTP status code 302 "found" to the client. While OK for human visitors, this method can be suboptimal from search engine optimization (SEO) viewpoint as search engines do not transfer the page rank assigned to the old URL to the new URL.permanent
301 redirect is a search engine friendly option. In this case the HTTP response code is set to 301. Google and Yahoo! specifically endorse this type of redirection and Bing is following the trend. 301 redirect preserves your search engine ranking for the redirected page.
It is also possible to leave the action prefix out. A virtual URI mapping that does not have a prefix does not re-process the request. It just changes the current URI in the AggregationState.
Examples
Default
Forward from /winter2016
to /marketing/campaigns/winter2016
.
Node name | Value |
---|---|
virtualUriMappings | |
winter2010 | |
class | info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping |
fromUri | /winter2016 |
toUri | forward:/marketing/campaigns/winter2016 |
Regular expression
Take requested page name and pass it as a productId
request parameter to a product detail page.
Node name | Value |
---|---|
virtualUriMappings | |
productIDs | |
class | info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping |
fromUri | /products/([0-9a-zA-Z-]+)\.html |
toUri | forward:/product/detail.html?productId=$1 |
The pattern [0-9a-zA-Z-]
in fromUri
means "any single character in the range of 0-9 or a-z or A-Z or the character -
literally". The plus character makes this a greedy pattern that matches one or more of the preceding token, and will match as many characters as possible before satisfying the next token. By enclosing the pattern in parentheses we create a capturing group ([0-9a-zA-Z-]+)
which can be referenced in the toUri
using $1
.
These request URIs:
example.com/products/Wayfarer-Retro.html
example.com/products/B00LBFSSYI.html
example.com/products/Sony-MDRZX100.html
would be mapped to these URIs:
example.com/product/detail.html?productId=Wayfarer-Retro
example.com/product/detail.html?productId=B00LBFSSYI
example.com/product/detail.html?productId=Sony-MDRZX100
Rotating
A request URI such as forward:/banner/image_*.jpg
will randomly forward the request to /banner/image_01.jpg
, /banner/image_02.jpg
or /banner/image_03.jpg
. A use case for this class is rotating images such as banner ads. The mapping displays a random ad on each page visit.
Node name | Value |
---|---|
virtualUriMappings | |
banner-ads | |
class | info.magnolia.virtualuri.mapping.RotatingVirtualUriMapping |
end | 3 |
fromUri | /dam/tours/banner/image.jpg |
padding | 2 |
start | 1 |
toUri | forward:/dam/tours/banner/image_*.jpg |
In addition to randomized ad distribution the class allows you to do basic A/B or multivariate testing. For example, create two images: A and B. Configure the mapping to display them randomly. Track visitor click-through rates to find out which image is more effective. You can use the Google Analytics module to track click events of any element such as images, buttons and teasers.
Host based
Forward the visitor to a German language version of the home page when the site is requested with the .de
country domain. Similarly, forward to a French version when the site is requested with the .fr
country domain. The matching pattern is in the host
property. The toUri
value under the parent node works as a fallback option. If no host name match is found, such as when the site is requested with acme.com
, forward to an English version.
Node name | Value |
---|---|
virtualUriMappings | |
language-by-domain | |
mappings | |
de | |
host | travel.de |
toUri | forward:/de/travel |
fr | |
host | travel.fr |
toUri | forward:/fr/travel |
class | info.magnolia.virtualuri.mapping.HostBasedVirtualUriMapping |
fromUri | / |
toUri | forward:/en/travel |
Google Sitemap
The mapping redirects the requests for sitemaps to the /sitemaps
node. The configuration is taken from the google-sitemap
module in the default installation of Magnolia:
Node name | Value |
---|---|
virtualUriMappings | |
siteMaps | |
class | info.magnolia.module.googlesitemap.config.mapping.SiteMapVirtualUriMapping |
prefix | redirect:/sitemaps |
Properties:
| SiteMapVirtualUriMapping compares source URI to names of sitemaps available in |
| Prefix prepended by the class. |
Mappings in the default installations of Magnolia
Module | Edition | Mapping class | From (Site) | To |
---|---|---|---|---|
(Author Instance) | EE |
| / | redirect:/.magnolia/admincentral |
(Author Instance) | CE |
| / | redirect:/.magnolia/admincentral |
(Public Instance) | EE |
| / | redirect:/travel.html |
(Public Instance) | CE |
| / | redirect:/travel.html |
google-sitemap | CE, EE |
| redirect:/sitemaps | |
rssaggregator | CE, EE |
| /rssFeeds/(.*) | redirect:/rss/?feedPath=/$1 |
rssaggregator | CE, EE |
| /planetFeeds/(.*) | redirect:/rss/?feedPath=/$1&generatorName=planet |
rssaggregator | CE, EE |
|
| redirect:/rss/?generatorName=category&categories=$1&siteRoot=/$2 |
tours | CE |
|
| forward:/travel/tour?tour=$1 |
tours | EE |
|
( | forward:/tour?tour=$1 |
tours | EE |
|
( |
|