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
. 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
/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
mappings content node contains URI to repository mappings.
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
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 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
/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
- Landing pages, geo or language specific pages
- Product pages
- Conversion pages
- Coupon codes, special offers
- Abbreviations, shorthands
For example, when a user visits
example.com/winter virtual URI mapping redirects them to
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.organd 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 theto 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/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.
Class that performs the mapping. See Classes.
Pattern to match in the requested URI.
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:
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.
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
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
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.
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
These request URIs:
would be mapped to these URIs:
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_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.
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.
You can use these action prefixes:
forwardhides 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.
redirectdisplays 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.
permanent301 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.