Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

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

Multisite is a feature that allows you to create multiple site definitions. Each site on your Magnolia can have a unique site definition, which means each can have its own theme, prototype, image variations and so on. Additionally, the multisite feature lets you map domain names to each site and where content should be served from when requested with a particular URL.

(warning) Magnolia 5.4.1+: The Multisite module also installs the so called fallback site.

Mappings

The multisite feature uses Magnolia''s core  URI2RepositoryMapping  mechanism to map a site definition to a site. This means that the mechanism examines the requested URL and serves content from one of Magnolia's workspaces accordingly.

The most common use case is mapping a URI to the website workspace and serving a Web page. Content is served from the website workspace by default if the request does not contain a prefix. If a prefix such as dam is detected the requested content is served from the workspace configured in the repository property. For example, if the requested URL contains /travel alone, the system maps the request to the website workspace. If the request contains /travel-demo you could map the request to the dam workspace instead.

Node nameValue
 fallback 

 travel

 

 mappings

 

 website

 

 URIPrefix

-

 handlePrefix

/travel

 repository

website

 sportstation

 

  mappings

 

  website

 

  URIPrefix

 

  handlePrefix

/sportstation

  repository

website

handlePrefix

The handlePrefix property defines the path where content should be served from. In the travel website the handle points to /travel and in sportstation to /sportstation. These are the respective root nodes of the sites. (Both are mapped to website workspace.)

The handle prefix is useful when you point it to a node deeper in the site hierarchy. For example, suppose you have built a winter holidays campaign in /travel/campaigns/winter2015. Setting handlePrefix to this path will apply the site definition to that branch of the site only. Now content for the site will be served from the branch.

URIPrefix

The URIPrefix property can be used to shorten URLs. 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.

Suppose your marketing campaign resides deep in the site hierarchy at /travel/campaigns/winter2015. First set handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting URIPrefix to /winter2015. Visitors who request the URLwww.example.com/winter2015 are served content from /travel/campaigns/winter2015 but the URL they type is short and friendly.

The standard URI2RepositoryMapping mechanism is enhanced by the following classes in the Multisite module. They add multisite and domain support.

  • info.magnolia.multisite.MultiSiteRootVirtualURIMapping
  • info.magnolia.multisite.MultiSiteURI2RepositoryManager
  • info.magnolia.multisite.MultiSiteURI2RepositoryMapping

Domains

You can map a domain name to a site in the /domains node. Mapping domains in Magnolia empowers editors as there is no need to configure a Web server. As a prerequisite, make sure the domain's DNS entries point to the Magnolia server. When visitors access the site with the domain name, content is served from the location identified by the handlePrefix.

Node nameValue

 travel

 

 domains

 

 travel-demo

 

 context

magnoliaPublic

 name

travel-demo.magnolia-cms.com
context

optional

Context path represents a web application such as magnoliaAuthor or magnoliaPublic. Context is needed to make links between sites work. You do not need to set the context property if you deploy to root context.

name

required

Domain name such as www.example.com.

port

optional

Port represents the port the web application was deployed on. Port is needed to make links between sites work. You do not need to set the port property if you deploy on port 80.

protocol

optional

HTTP or HTTPS. Default is HTTP.

You can map multiple domain names to the same site. This is useful for covering top-level domains such as .net and .org and setting localized prefixes for sites like  de.example.com fr.example.com .

Virtual URIs

Much of what can be done with domain mapping can also be done with virtual URIs. As a rule, virtual URI mapping should only be used for a small number of pages and for temporary purposes. For example, you could use a virtual URI for a Christmas campaign but once your campaign becomes a Christmas shop you should assign a site definition to it and make it a site. Defining a site opens up options such as themes and i18n support.

Request matcher rules

When a request arrives to Magnolia it needs to be matched to a site so that the right content is served.  MultiSiteManager  is the class that matches requests to a site in a multisite environment. Request matcher rules ensure that the correct content is served. You can configure request matcher rules in the module configuration. 

For complex multisite structures, you can configure precise matcher rules that take account of every possibility. Matcher classes for all properties in the site definition, and well as the site name, are provided.

The rules are resolved in the order in which they are configured, with higher configurations taking precedence. All rules are evaluated and the best-matching site served. The rules apply to all configured sites.

The default configuration in /modules/multisite/config/rules should suffice in most environments.

Node nameDescription
 modules 

 multisite

 

 config

 

 rules

 

 uri-starts-with-sitename

 

 matchers

 

 0

 

 class

info.magnolia.multisite.sites.matchers.SiteNameMatcher

 description

URI starts with site name: /site-name

 multipleMatchesPossible

false

 domain-and-uri-prefix-not-empty

 

 matchers

 

 0

 

 class

info.magnolia.multisite.sites.matchers.DomainMatcher

 1

 

 class

info.magnolia.multisite.sites.matchers.NotEmptyUriPrefixMatcher

 description

 Domain and not empty uri prefix (subsites)

 multipleMatchesPossible

 false

 domain-and-handle-not-empty

 

 domain-and-site-uri-prefix-empty

 

 uri-prefix-not-empty

 

 handle-not-empty

 

Properties:

class

required

Matcher class.

description

optional

Describes what the configuration does.

multipleMatchesPossible

optional, default is false

Whether the rule allows more than one match. When set to false, if two site definitions match, the rule is bypassed. 

Matcher classes:

  • info.magnolia.multisite.sites.matchers.SiteNameMatcher: Checks the sitename (root node of the site in Pages).
  • info.magnolia.multisite.sites.matchers.DomainMatcher: Checks the domains configured in the site definition.
  • info.magnolia.multisite.sites.matchers.NotEmptyUriPrefixMatcher: Checks for a URIPrefix property in the mappings node of the site definition.
  • info.magnolia.multisite.sites.matchers.NotEmptyHandleMatcher: Checks for a handlePrefix property in the mappings node of the site definition.
  • info.magnolia.multisite.sites.matchers.SiteHasEmptyUriPrefixMatcher: Checks for an empty URIPrefix property.

Rules:

  • uri-starts-with-sitename: Site name matches. URI starts with site name: /<site-name>. Single-class rule uses SiteNameMatcher. Multiple matches not possible.
  • domain-and-uri-prefix-not-empty: Domain matches and URI prefix is not empty. Used for subsites. Dual-class rule usesDomainMatcher and NotEmptyUriPrefixMatcher. If a matching domain and URI prefix are found, the rule is bypassed. Multiple matches not possible.
  • domain-and-handle-not-empty: Domain matches and handle is not empty. Used for AdminCentral access. Dual-class rule usesDomainMatcher and NotEmptyHandleMatcher. If a matching domain and handle prefix are found, the rule is bypassed. Multiple matches not possible.
  • domain-and-site-uri-prefix-empty: Domain matches and the URI prefix is empty. Used for main site. Dual-class rule usesDomainMatcher and SiteHasEmptyUriPrefixMatcher. Multiple matches not possible.
  • uri-prefix-not-empty: URI prefix is not empty. Used for subsites that have a URI prefix. Single-class rule usesNotEmptyUriPrefixMatcher.  Multiple matches possible.
  • handle-not-empty: Handle matches. Used for AdminCentral access. Singe-class rule uses NotEmptyHandleMatcher. Multiple matches possible.

Custom matchers

You can write your own custom matcher classes to create new rules. The custom class should extend  AbstractMatcher that implements the  RequestMatcher interface. 

  • No labels