Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
URI mapping is a way to redirect an incoming request to the location of the content. The URI2RepositoryMapping mechanism determines which repository node should be served when a particular URI is requested. Virtual URI mapping allows you to create short, convenient URLs that do not match the site hierarchy exactly.
URI stands for Uniform Resource Identifier. There are basically two kinds of URIs: names (URN) and locators (URL). A name tells you what the resource is. A typical example of a URN is the ISBN system used to identify books. For example, urn:isbn:0-199-53572-8
identifies Moby Dick by Herman Melville. A locator tells you where the resource is. The most common type of locator is a Web address (URL) such as http://www.example.com/hello.html
. URIs can be absolute (www.example.com/hello.html
) or relative (/hello.html
). In this article we use the parent term URI although all the examples are actually locators (URL).
The URI2RepositoryMapping mechanism determines which repository node should be served when a particular URI is requested. The most common use case is mapping a URI to the website
repository. Magnolia's standard
URI2RepositoryMapping
mechanism is used to map a requested URL to one of the workspaces.
If a prefix such as dam
is detected in the request the requested asset is served from the repository given in the repository
property. A handle can be used to build the URI. For example, if the requested URL contains /travel
alone, the system can be configured to map the request to the website workspace. On the other hand, if the request contains /travel/docs
it could be mapped to the dam
workspace.
The mappings
content node contains URI to repository mappings.
Node name | Value |
---|---|
travel | |
mappings | |
website | |
URIPrefix |
|
handlePrefix | /travel |
repository | website |
The handlePrefix
property defines where content should be served from. In the travel
demo website the handle is /travel
and in the sportstation
website the handle is /sportstation
. These are the respective root nodes of the sites.
The handle prefix is useful when you point it to a node deeper in the site hierarchy. Suppose you have a campaign in /travel/campaigns/winter
. Setting handlePrefix
to this path will apply the site definition to that subtree only. Now content for the site will be served from the subtree. In the same site definition you could define a custom winter theme for the campaign and assign a vanity URL such as winter.example.com
. Visitors who access the URL are served content from /travel/campaigns/winter
, not from the site root, and they see the campaign specific theme.
The URIPrefix
property is used to inject a path into a URL in order to shorten it. Shorter URLs are easier to remember, quicker to type, take less space in print ads, and are ranked more favorably by search engines than content deep down in the site hierarchy.
Suppose your marketing campaign resides deep in the hierarchy at /travel/marketing/campaigns/2016/winter
. First set handlePrefix
to this path so that content is served from the right place. Then shorten the URL by setting URIPrefix
to /winter
. Visitors who access the site at www.example.com/winter
are served content from /travel/marketing/campaigns/2016/winter
but the URL is short and friendly.
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. Out of convenience, it is shorter and easier to remember than the true location.
The list of virtual URI mappings configured is displayed in the About Magnolia app Virtual URI Mappings tab.
Virtual URIs are commonly used in Internet marketing for:
For example, when a user visits example.com/winter
virtual URI mapping redirects them to example.com/travel/marketing/campaings/2016/winter
.
There are also utility reasons for redirecting URLs, related to day-to-day site maintenance:
example.net
and example.org
and redirecting them to your primary site example.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.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.
Create virtual URI mappings in a virtualURIMapping
folder inside your module configuration.
Example: A mapping named enterprise
forwards users from example.com/ee
to example.com/enterprise-edition
. Here we use the DefaultVirtualURIMapping
class. It simply 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> | |
virtualURIMapping | |
enterprise-edition | |
class | info.magnolia.cms.beans.config.DefaultVirtualURIMapping |
fromURI | /ee |
toURI | forward:/enterprise-edition |
Properties:
class | required Class that performs the mapping. See Classes. |
fromURI | required Pattern to match in the requested URI. |
toURI | required Concrete URI where the request is mapped to. |
You should create the virtualURIMapping
folder at the top level inside module configuration. See these examples in the demo:
/modules/tours/virtualURIMapping
/modules/ui-admincentral/virtualURIMapping
/modules/activation/virtualURIMapping
You can create your URI mappings in these folders while developing and testing. Magnolia will find them. However, for production use we recommend that you create your own module and a virtualURIMapping
folder inside it.
/modules/<my-module>/virtualURIMapping/
Magnolia provides four ready-made classes that perform virtual URI mapping: default, regular expression, rotating and host based. You can also write your own implementation.
DefaultVirtualURIMapping maps a virtual URI to a content path. This is the simplest and most common type.
Example: Forward from /winter2016
to /marketing/campaigns/winter2016
.
Node name | Value |
---|---|
virtualURIMapping | |
winter2010 | |
class | info.magnolia.cms.beans.config.DefaultVirtualURIMapping |
fromURI | /winter2016 |
toURI | forward:/marketing/campaigns/winter2016 |
5.4.6+ 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.
Example: Take requested page name and pass it as a productId
request parameter to a product detail page.
Node name | Value |
---|---|
virtualURIMapping | |
productIDs | |
class | info.magnolia.cms.beans.config.RegexpVirtualURIMapping |
fromURI | /products/([0-9A-Z]+)\.html |
toURI | forward:/product/detail.html?productId=$1 |
The pattern [0-9A-Z]
in fromURI
means "any single character in the range of 0-9 or A-Z". 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-Z+])
which can be referenced in the toURI
using $1
.
These request URIs:
example.com/products/Wayfarer-Retro.html
example.com/products/B00LBFSSYI.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
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 between start
(default is 1) and end
minus one (default is 3).
An additional property padding
specifies the desired width of the string. Zeroes are added to the left of the integer to make all strings equally wide. Default width is 2.
Example: 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 |
---|---|
virtualURIMapping | |
banner-ads | |
class | info.magnolia.cms.beans.config.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.
HostBasedVirtualURIMapping forwards the request to a different URI depending on the requested host name.
Example: 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 |
---|---|
virtualURIMapping | |
language-by-domain | |
mappings | |
de | |
host | travel.de |
toURI | forward:/de/travel |
fr | |
host | travel.fr |
toURI | forward:/fr/travel |
class | info.magnolia.cms.beans.config.HostBasedVirtualURIMapping |
fromURI | / |
toURI | forward:/en/travel |
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. 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 .