Page tree
Skip to end of metadata
Go to start of metadata

This type of URI mapping determines which repository node should be served when a particular URI is requested.

How URI to repository mapping works

Magnolia's URI2RepositoryMapping  mechanism is used to map a requested URL to one of the workspaces . The most common use case is mapping a URI to the website repository, but other repositories can be addressed as well. The mechanism allows finetuning the mapping of the requests through prefixes (handles). 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 (in the context of a Site definition). On the other hand, if the request contains /travel/docs it could be mapped to the  dam workspace.

Mapping managers and Magnolia editions

In order to know where to configure a URI mapping rule, you should understand how the URI-to-repository managers deal with this type of mapping.

URI to repository mapping in Magnolia is handled by two different managers depending on the edition you use:

EditionURI2Repository manager class
Communityinfo.magnolia.cms.beans.config.URI2RepositoryManager
Enterpriseinfo.magnolia.multisite.MultiSiteURI2RepositoryManager

The Community Edition allows only one site, hence its manager searches for and applies the mapping configurations defined directly at the server level ( /server/URI2RepositoryMapping/mappings/ ).

In the Enterprise Edition, the manager first searches for mapping configuration for each site stored under the mappings node in the multisite module and applies a mapping rule if it finds one. If not, it defaults to the mapping configuration(s) set at the server level ( /server/URI2RepositoryMapping/mappings/ ), in the same way as the manager of the Community Edition.

Configuring the mappings

Configuration properties

The key configuration properties for URI to repository mappings are:

  • URIPrefix
  • handlePrefix
  • repository

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.

In Magnolia 5.5.2+, the default values of the URIPrefix properties in /server/URI2RepositoryMapping/mappings/ come with a trailing slash, for example /contacts/ instead of just /contacts , to prevent URI mapping conflicts for root-level pages having the same name as the URI prefix.

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.

repository

The repository property defines the name of the target repository for the requested content.

Where to configure

Community and Enterprise editions

In both editions, Community and Enterprise, the mappings for repositories such as dam or resources are usually set in the configuration of the server at /server/URI2RepositoryMapping/mappings/ . Each repository may use a specific mapping class. Magnolia comes with the the following repository-specific classes:

RepositoryClass
daminfo.magnolia.dam.core.link.DamURI2RepositoryMapping
resourcesinfo.magnolia.module.resources.mapping.URI2ResourcesRepositoryMapping

The  website repository has a pre-configured mapping at the server level in the Community as well as in the Enterprise edition.

Enterprise Edition only

The Enterprise Edition can host multiple sites and allows you to configure URI to repository mappings separately for each of the sites. Typically, this is done for the website repository, but other repositories are not excluded. The configuration takes place in the multisite module

  • /modules/multisite/config/sites/<site1-name>/mappings/
  • /modules/multisite/config/sites/<site2-name>/mappings/
  • /modules/multisite/config/sites/<site2-name>/mappings/
  • etc.

Configuration examples

Community Edition

Node name

Value

 server
 

 ....

 

 URI2RepositoryMapping

 

 mappings

 

 website

 

 URIPrefix

 

 handlePrefix

 

 repository

website

 dam

 

 URIPrefix

/dam/ 

 class

info.magnolia.dam.core.link.DamURI2RepositoryMapping

 handlePrefix

 

 repository

dam

 resources

 

 contacts

 

 sitemaps

 

 ...

 

 class

 info.magnolia.cms.beans.config.URI2RepositoryManager
Enterprise Edition
Server part

Node name

Value

 server
 

 ....

 

 URI2RepositoryMapping

 

 mappings

 

 website

 

 URIPrefix

 

 handlePrefix

 

 repository

website

 dam

 

 URIPrefix

/dam/ 

 class

info.magnolia.dam.core.link.DamURI2RepositoryMapping

 handlePrefix

 

 repository

dam

 resources

 

 contacts

 

 sitemaps

 

 personas

 

 ...

 

 ...

 info.magnolia.multisite.MultiSiteURI2RepositoryManager
multisite module (default configuration)

Node name

Value

 fallback


 mappings


 extends

override

(The fallback node extends the travel site.)

Node name

Value

 travel


 mappings


 website


 URIPrefix


 handlePrefix

/travel

 repository

website

Node name

Value

 sportstation


 mappings


 website


 URIPrefix


 handlePrefix

/sportstation

 repository

website

  • No labels