Multisite

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.

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

Mappings

The multisite feature uses Magnolia''s core

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") 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 name	Value
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 name	Value
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 name	Description
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.

Page tree