Page History

...

You can create virtual URI mappings in the virtualUriMappings folder inside your module configuration.

Info

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

Multiexcerpt include

MultiExcerptName	tooManyURImappings
PageWithExcerpt	_Known issues

...

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.

Image Added

Via YAML

You can configure virtual URI mappings in a YAML definition file inside a light module folder:

info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping


fromUri: /ee
toUri: forward:/enterprise-edition

Code Block

language	yaml
title	<my-module>/virtualUriMappings/enterprise-edition.yaml
linenumbers	true

class:

Advanced Tables - Table Plus

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

Node name

Value

Mgnl f

<my-module>

Mgnl f

virtualUriMappings

Mgnl n

enterprise-edition

Mgnl p

class

Mgnl p

fromUri

/ee

Mgnl p

toUri

Via YAML

You can configure virtual URI mappings in a YAML definition file inside a light module folder:

Code Block

language	yaml
title	<my-module>/virtualUriMappings/enterprise-edition.yaml
linenumbers	true

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 `MultiSiteRegexpVirtualUriMapping` class) Specifies the site that should be used for the mapping.
`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 `MultiSiteRegexpVirtualUriMapping` class) 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:

...

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

...

Node name

...

Value

...

Mgnl f

<my-module>

...

Mgnl f

virtualUriMappings

...

Mgnl n

europe

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping

...

Mgnl p

fromUri

...

/customer-support-europe.html

...

Mgnl p

toUri

...

forward:/europe/cust-support.html

...

Mgnl n

usa

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping

...

Mgnl p

fromUri

...

/customer-support-usa.html

...

Mgnl p

toUri

...

forward:/usa/cust-support.html

Image Added

Mapping classes

Magnolia provides seven ready-made classes that perform virtual URI mapping:

info.magnolia.virtualuri.mapping.*
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
  renderType asynchronous
  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.
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping
  renderType asynchronous
  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.
- Javadoc resource link
  className

...

Mgnl n

asia-australia

...

Mgnl n

asia

Mgnl p

...

- info.magnolia.virtualuri.mapping.

...

- RotatingVirtualUriMapping

...

- renderType

...

/customer-support-asia.html

...

Mgnl p

toUri

...

forward:/asia/cust-support.html

- asynchronous
  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.
- Javadoc resource link
  className

...

Mgnl n

australia

Mgnl p

...

- info.magnolia.virtualuri.mapping.

...

- HostBasedVirtualUriMapping

...

- renderType

...

/customer-support-australia.html

...

Mgnl p

toUri

...

Mapping classes

...

- asynchronous
  forwards the request to a different URI depending on the requested host name.
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.
*
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.DefaultVirtualUriMappingHostBasedRegexpVirtualUriMapping
  renderType asynchronous
  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. 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.
info.magnolia.multisite.mapping.*
- javadoc-resource-javadoc-resource-link-macro
  className info.magnolia.virtualurimultisite.mapping.RegexpVirtualUriMappingMultiSiteRootVirtualUriMapping
  renderType asynchronous
  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. is a special class which specifies the root of a site if site matching returns null.
- javadoc-resource-
  javadoc-resource-
  link-macro
  className info.magnolia.
  virtualuri
  multisite.mapping.
  RotatingVirtualUriMapping
  MultiSiteRegexpVirtualUriMapping
  renderType asynchronous
  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.
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.HostBasedVirtualUriMapping
  renderType asynchronous
  forwards the request to a different URI depending on the requested host name.
- Javadoc resource link
  className info.magnolia.virtualuri.mapping.HostBasedRegexpVirtualUriMapping
  renderType asynchronous
  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.
info.magnolia.multisite.mapping.*
Javadoc resource link
className info.magnolia.multisite.mapping.MultiSiteRootVirtualUriMapping
renderType asynchronous
is a special class which specifies the root of a site if site matching returns null.

javadoc-

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.

You can also write your own implementation.

The patterns for regular expressions in the regex-based classes are defined in java.util.regex.Pattern.

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

javadoc-resource-link-macro

className	info.magnolia.

...

cms.

...

core.

...

AggregationState
renderType	asynchronous

...

.

Examples

Default

Forward from /winter2016 to /marketing/campaigns/winter2016.

Image Added

Regular expression

Info

icon	false

Always test your regex-based virtual URI configurations thoroughly before applying them to a live environment. The configurations that seem correct on the surface can yield unwanted results. For example, using boundary matchers (the hat ^, the dollar $, and others) in fromUri and toUri may improve your matches otherwise a simple value such as /foobar.html will be matched not only in /foobar.html but also in /something/foobar.html.

Take requested page name and pass it as a productId request parameter to a product detail page.

Image Added

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

Image Added

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.

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 hostname match is found, such as when the site is requested with acme.com, forward to an English version.

Image Added

You can also write your own implementation.

The patterns for regular expressions in the regex-based classes are defined in java.util.regex.Pattern.

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

Javadoc resource link

className	info.magnolia.cms.core.AggregationState
renderType	asynchronous

.

Examples

Default

Forward from /winter2016 to /marketing/campaigns/winter2016.

...

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

...

Node name

...

Value

...

Mgnl f

virtualUriMappings

...

Mgnl n

winter2010

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping

...

Mgnl p

fromUri

...

/winter2016

...

Mgnl p

toUri

...

forward:/marketing/campaigns/winter2016

Regular expression

Info

icon	false

Always test your regex-based virtual URI configurations thoroughly before applying them to a live environment. The configurations that seem correct on the surface can yield unwanted results. For example, using boundary matchers (the hat ^, the dollar $, and others) in fromUri and toUri may improve your matches otherwise a simple value such as /foobar.html will be matched not only in /foobar.html but also in /something/foobar.html.

Take requested page name and pass it as a productId request parameter to a product detail page.

...

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

...

Node name

...

Value

...

Mgnl f

virtualUriMappings

...

Mgnl n

productIDs

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping

...

Mgnl p

fromUri

...

/products/([0-9a-zA-Z-]+)\.html

...

Mgnl p

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

...

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

...

Node name

...

Value

...

Mgnl f

virtualUriMappings

...

Mgnl n

banner-ads

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.RotatingVirtualUriMapping

...

Mgnl p

end

...

3

...

Mgnl p

fromUri

...

/dam/tours/banner/image.jpg

...

Mgnl p

padding

...

2

...

Mgnl p

start

...

1

...

Mgnl p

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.

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 hostname match is found, such as when the site is requested with acme.com, forward to an English version.

...

heading	0
enableHeadingAttributes	false
enableSorting	false
class	m5-configuration-tree
enableHighlighting	false

...

Node name

...

Value

...

Mgnl f

virtualUriMappings

...

Mgnl n

language-by-domain

...

Mgnl n

mappings

...

Mgnl n

de

...

Mgnl p

host

...

travel.de

...

Mgnl p

toUri

...

forward:/de/travel

...

Mgnl n

fr

...

Mgnl p

host

...

travel.fr

...

Mgnl p

toUri

...

forward:/fr/travel

...

Mgnl p

class

...

info.magnolia.virtualuri.mapping.HostBasedVirtualUriMapping

...

Mgnl p

fromUri

...

/

...

Mgnl p

toUri

...

Mappings in the default installations of Magnolia

...

Page tree

Versions Compared

Old Version 6

New Version Current

Key

Via YAML

Via YAML

Properties

Properties

A catalog of mappings

Mapping classes

Mapping classes

Action prefixes

Examples

Default

Regular expression

Rotating

Host-based

Action prefixes

Examples

Default

Regular expression

Rotating

Host based

Mappings in the default installations of Magnolia