URI mapping

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.

About URIs and URLs

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

URI to repository mapping

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 

 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

handlePrefix

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.

URIPrefix

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

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.

Where to use

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

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:

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

Configuration

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:

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/

Classes

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.

Default

 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.

Regular expression

 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
• 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

 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.

Host based

 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

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

.