Multisite definition configuration

This page is about site definition configuration in the context of multisite. It explains how to configure multiple, distinct site definitions which require the definition of domains and mappings nodes.

For site rules configuration details, see Site resolution rules.

We assume that you already know some basics about Magnolia site definition configuration (such as prototypes, themes, imaging variations and sitefn templating functions).

Site definition

Go to Configuring a site definition to configure a site definition.

Site definition name

The node name of the site definition is called site-definition-name.

If a site is properly configured, it can be accessed using the following URL:

<protocol>://<domain>:<port>/<context>/<site-definition-name>

This only works if the domain part of the URL is different from the domain that is mapped to the site of the given site-definition-name.

Mappings and domains

The mappings and domains nodes are required in a multisite context. You must create a least one entry on both mappings and domains to ensure a proper site definition for a distinct site.

Example:

<my-light-module>/sites/comics.yaml
mappings:
  website:
    URIPrefix:
    handlePrefix: /comics
    repository: website
  jolly-jumper:
    URIPrefix: /jollyjumper
    handlePrefix: /comics/belgian-comics/morris/lucky-luke/jolly-jumper
    repository: website
domains:
  best-comics:
    name: www.best-comics.net

The site defined above allows you to access:

  • The content node /comics via the URL http://www.best-comics.net.

  • The content node /comics/belgian-comics/morris/lucky-luke/jolly-jumper via the URL http://www.best-comics.net/jollyjumper.

Use different values for the site-definition-name and the name of the mapped node (handlePrefix).

mappings configuration

The mapping nodes define the JCR content nodes (usually page nodes) assigned to the site definition.

A mapping has the following properties:

Property Description

<mapping-node>

required

Each site can contain multiple mappings. The name of a mapping node is arbitrary (in the example above, the node name is website).

The corresponding class for a mapping is info.magnolia.cms.beans.config.URI2RepositoryMapping.

     repository

required

Name of the JCR workspace the mapping applies to.

     handlePrefix

required

The path in the workspace the content is served from.

     URIPrefix

required

Creates a node handle based on a URI. By default, a content request that does not contain a prefix is served from the node defined on handlePrefix of the given repository.

The URIPrefix property can be used to shorten URLs. (See the jolly-jumper example above and the Multisite example - Shorten URL with handlePrefix example.) Short 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.

If this property is not set, info.magnolia.multisite.MultiSiteURI2RepositoryManager throws an exception (leading to a runtime exception and a server error 500). Add the property with an empty value (or /) if you do not need it.

Note that URIPrefix configuration can also be applied in modules independent from site definitions.

Configuration in the site definition overrides the configuration in /server/URI2RepositoryMapping/mappings/<workspace>, resulting in site-specific definitions.

domains configuration

A domain node assigns a domain to the given site definition. It defines how the above mapped content node(s) can be accessed by URL. You can map multiples domain to the same site.

A domain mapping has the following properties:

Property Description

<domain-node>

required

The name of a domain mapping node is arbitrary. You can apply multiple domain nodes per site.

     name

required

Domain name such as http://www.best-comics.net.

     port

optional

Port represents the port the web application was deployed on.

Default is 80.

     protocol

optional

HTTP or HTTPS.

Default is HTTP.

     context

optional

The context path of the Magnolia instance webapp such as magnoliaAuthor or magnoliaPublic.
You do not need to set the context property if the webapp is served from root context.
The optional properties port, protocol and context are only used to build links between the pages of different sites. In a typical production setup, where you serve the webapps from the root context on different domains, you do not have to set port and context.

Extending site definitions

Another configuration strategy is to have one site definition for your main site with a template prototype that you can then reuse on other site definitions. This is a common alternative to having multiple independent site definitions.

In the example below, site-2 and site-3 inherit from site-1.

Node or property Value

site-1

site-2

     extends

../site-1

site-3

     extends

../site-1
Inheriting mappings and domain can lead to unexpected results and may destroy your site setup.

When extending site definitions, turn off inheritance for mapping and domains by using @extends=override.

Node or property Value

site-1

site-2

     extends

../site-1

     mappings

         extends

override

     domains

         extends

override

Make sure you have no unwanted virtualURIMapping redirections on the public context.

Use the Configuration app on the public context and search for virtualURIMapping.

On a standard Magnolia bundle, you most probably find the node

/modules/ui-admincentral/virtualURIMapping/default

which redirects to

/.magnolia/admincentral

You must delete the node to ensure a request to http://<your-domain>/ really serves the root page of your site. See an example.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules