Page History

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. 

...

The URIs can be either absolute or relative within the web application in which case the context path is added automatically. For example:

• Relative
  
  fromUri: /winter2016
toUri: forward:/marketing/campaigns/winter2016

• Relative
  fromUri: /winter2016
toUri: forward:/marketing/campaigns/winter2016Absolute
  
  fromUri: /winter2016
toUri: forward:https://www.example.com/marketing/campaigns/winter2016.html

The mappings registry

Mappings The mappings are delegated to a separate module ( virtual-uri ) through the  info.magnolia.virtualuri.VirtualUriFilter  class and are stored in their own registry ( VirtualUriRegistry ), which allows to reference each mapping also in YAML definition files. All virtual URI mappings can be located via the Definitions app no matter whether they come from JCR or a YAML file:

You can also check the mappings in the About app's Virtual URI Mappings tab, or by searching Alternatively, search the config space with the JCR browser app:

Image RemovedImage Added

Where to use virtual mappings

...

Via YAML

( Magnolia 5.5.6+) You You can configure virtual URI mappings in a YAML definition file inside a light module folder:

...

A catalog of mappings

( Magnolia 5.5.6+) 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:

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:

...

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

• info.magnolia.virtualuri.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.
  ( Magnolia 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.

• 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 info.magnolia.virtualuri.mapping.RotatingVirtualUriMapping 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

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

  asynchronous

   allows you to specify a regular expression pattern that matches a sequence of characters.
info.magnolia.module.googlesitemap.config.mapping.*
• 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 info.magnolia.

  module.googlesitemap

  virtualuri.

  config.

  mapping.

  SiteMapVirtualUriMapping

  RotatingVirtualUriMapping renderType asynchronous

  compares source URI to names of sitemaps available in the googleSitemaps workspace and prepends the prefix.
info.magnolia.multisite.mapping.* 

•  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.multisitevirtualuri.mapping.MultiSiteRootVirtualUriMappingHostBasedVirtualUriMapping renderType asynchronous

   is a special class which specifies the root of a site if site matching returns null .  forwards the request to a different URI depending on the requested host name.

• Javadoc resource link
  className info.magnolia.multisitevirtualuri.mapping.MultiSiteRegexpVirtualUriMappingHostBasedRegexpVirtualUriMapping renderType asynchronous

   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.

...

Deprecated classes

...

• •  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.module.googlesitemap.config.mapping.*
  

  • Javadoc resource link
    asynchronous className info.magnolia.module.googlesitemap.config.mapping.SiteMapVirtualUriMapping renderType asynchronous

    compares source URI to names of sitemaps available in the googleSitemaps workspace and prepends the prefix.
• info.magnolia.multisite.mapping.* 
  

  • Javadoc resource link
    className info.magnolia.multisite.MultiSiteRootVirtualURIMapping renderType asynchronous
    Javadoc resource link
    className info.magnolia.multisite.MultiSiteRegexpVirtualURIMappingmapping.MultiSiteRootVirtualUriMapping renderType asynchronous

With the introduction of the virtual-uri module in Magnolia 5.5.6, the following classes have been deprecated:

• info.magnolia.cms.beans.config.*
  •  is a special class which specifies the root of a site if site matching returns null . 
  • className

    Javadoc resource link
    rangeHigherVersion 5.5.6 className info.magnolia.cms.beans.config.DefaultVirtualURIMapping renderType asynchronous
    Javadoc resource link
    rangeHigherVersion	5.5.6
    className info.magnolia.multisite.mapping.MultiSiteRegexpVirtualUriMapping renderType asynchronous

     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 .

Anchor
deprecated-classes deprecated-classes

Deprecated classes

The following classes have been deprecated with the release of Magnolia 5.6:

• info.magnolia.cmsmodule.beansgooglesitemap.config.*
  RegexpVirtualURIMappingrenderTypeasynchronous
  • 5.5.6

    Javadoc resource link
    rangeHigherVersion
    className info.magnolia.cmsmodule.beansgooglesitemap.config.RotatingVirtualURIMappingSiteMapVirtualUriMapping renderType asynchronous

• info.magnolia.multisite.*
  • 5.5.6

    Javadoc resource link
    rangeHigherVersion
    className info.magnolia.cms.beans.config.HostBasedVirtualURIMappingmultisite.MultiSiteRootVirtualURIMapping renderType asynchronous

  • rangeHigherVersion

    Javadoc resource link
    5.5.6 className info.magnolia.cms.beans.configmultisite.HostBasedRegexpVirtualURIMappingMultiSiteRegexpVirtualURIMapping renderType asynchronous

Action prefixes

...

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 

Examples

Default

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

...

Regular expression

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

The pattern [0-9a-9AzA-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 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-9AzA-Z-]+]) which can be referenced in the toUri using $1.

...

Anchor
GoogleSitemapVirtualUriMapping GoogleSitemapVirtualUriMapping

Google Sitemap

The mapping redirects the requests for sitemaps to the /sitemaps node. The configuration is taken from the google-sitemap module in the default installation of Magnolia:

Properties:

Mappings in the default installations of Magnolia