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  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 /demo-project alone, the system can be configured to map the request to the website repository. On the other hand, if the request contains /demo-project/docs it could be mapped to the dms repository.

The mappings content node contains URI to repository mappings.

handlePrefix

The handlePrefix property defines where content should be served from. In the demo-project website the handle points to /demo-project and in demo-features to /demo-features. 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. For example, suppose you have a campaign in /demo-project/campaigns/winter2010. 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 winter2010.example.com. Visitors who access the URL are served content from /demo-project/campaigns/winter2010, 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 /demo-project/marketing/campaigns/2010/winter. First set handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting URIPrefix to /winter2010. Visitors who access the site at www.example.com/winter2010 are served content from /demo-project/marketing/campaigns/2010/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.

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/winter2010 virtual URI mapping redirects them to example.com/marketing/campaings/2010/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

Virtual URI mapping is done with a virtualURIMapping configuration. The configuration specifies a fromURI pattern to match, the actual concrete toURI where the request is mapped to, and a class that performs the mapping. You can name the configuration any way you want. Choose a name that describes its purpose.

Example: A mapping named enterprise-edition forwards a user who enters address www.example.com/ee to www.example.com/enterprise-edition. Here we use the DefaultVirtualURIMapping class. It simply maps one URI to another. This example could be used to ensure that external links that point to www.example.com/ee still work when the target page is renamed.

The virtualURIMapping folder and its subnodes are commonly placed at the top level inside a module. In the demo author instance you will find examples such as:

/modules/ui-admincentral/virtualURIMapping/
/modules/activation/virtualURIMapping/
/modules/standard-templating-kit/virtualURIMapping/

You can create your own mappings under any of the above folders while you test. Magnolia will find them. However, for production use we recommend that you create a dedicated module for your own project and create a new virtualURIMapping folder inside it.

/modules/myModule/virtualURIMapping/

Classes

Magnolia provides four ready-made classes that perform virtual URI mapping: default, regular expressions, rotating and host based. In addition to these four you can also write your own class. See the SVN links for examples.

Default

Maps a virtual URI to a content path. This is the simplest and most common type. In the configuration example below, a user enters www.example.com/winter2010 and Magnolia forwards the user to www.example.com/marketing/campaigns/winter.

Class: DefaultVirtualURIMapping (source)

 5.3.15+ 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

A regular expression allows you to specify a 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 references to the regexp matches.

In the example below we match product IDs in the page name and map them to values passed in the productId attribute in the URI.

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.

As a consequence, these request URIs:

www.example.com/products/123.html
www.example.com/products/ABC.html
www.example.com/products/MGNL437.html

would be mapped to these URIs:

www.example.com/product/detail.html?productId=123
www.example.com/product/detail.html?productId=ABC
www.example.com/product/detail.html?productId=MGNL437

Class RegexpVirtualURIMapping (source)

Rotating

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.

In the example below 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.

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.

Class:  RotatingVirtualURIMapping (source)

Host based

Host-based virtual URI mapping forwards the request to a different URI depending on the requested host name.

In the example below we forward the visitor to a German language version of the home page when the site is requested with the .de country domain. Similarly, we 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, for example when the site is requested with acme.com, we forward to an English version.

Class:  HostBasedVirtualURIMapping  (source)

Action prefixes

You can choose from three types of 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 .