Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
Multisite support is an Enterprise Edition feature provided by the Extended Templating Kit module. It allows you to manage multiple websites in a single Magnolia instance. Each site has its own site definition which can apply unique templates, themes, variations, domains and locales to the site. Besides making each site unique, the multisite feature lets you inherit features from another site.
You can use multisite support for microsites, campaigns, events and product launches. A microsite can inherit page templates from the parent site, yet have its own theme and domain. You save time and effort by not having to create new page and component templates. Sites that are localized to user's language or geographical area can inherit templates and themes from a parent site and add its own locales to support additional languages and country-specific domains. Watch a video of this feature.
A site definition is responsible for assigning the following elements to a website:
Site definitions are configured in Templating Kit > Site Definitions. The
default site definition is fallback configuration for all sites and is the basis for site-specific definitions. The default configuration is explained in Site definition.
default site definition includes:
Each site requires its own site definition. The individual site definitions use the extends mechanism to extend the
default definition. This means they use the
default configuration and make exceptions for site-specific additions and changes.
Here are a few suggestions that you can configure in an individual site definition:
The multisite feature uses Magnolia's core UpdateURI2RepositoryMappings (Git) 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
dms is detected the requested content is served from the workspace configured in the
repository property. For example, if the requested URL contains
/demo-project alone, the system maps the request to the
website workspace. If the request contains
/demo-project/docs you could map the request to the
dms workspace instead.
handlePrefix property defines the path where content should be served from. In the
demo-project website the handle points to
/demo-project and in
/demo-features. 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. For example, suppose you have built a winter clothing campaign in
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. In the same site definition you could configure a custom winter theme for the campaign and assign a vanity URL such as
winter2012.example.com. Visitors who request the vanity URL are served content from
/demo-project/campaigns/winter2012, not from the site root, and they see the campaign specific theme.
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 site hierarchy at
/demo-project/marketing/campaigns/2012/winter. First set
handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting
/winter2012. Visitors who request the URL
www.example.com/winter2012 are served content from
/demo-project/marketing/campaigns/2012/winter but the URL they type is short and friendly.
The standard URI2RepositoryMapping mechanism is enhanced by the following classes in the Extended Templating Kit. They add multisite and domain support.
You can map a domain name to a site in the
/domains node. Mapping domains in the CMS empowers editors as there is no need to configure a Web server. You still need to own the domain. Mapping it in Magnolia is not enough. Register a domain name with a registrar and make sure its DNS entries point to the server hosting your Magnolia instance. When visitors access the site with the domain name, content is served from the location identified by the
context: Context path represents a web application such as
magnoliaPublic. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
name: Domain name such as www.example.com.
port: Port number such as 8080. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
protocol: Protocol such as HTTPS. Default is HTTP.
The classes that provide domain mapping functionality are:
DomainNamePathTransformerconstructs URLs by prefixing the path with
Server.getDefaultBaseUrl()and the domain name.
CrossSiteAbsolutePathTransformerconstructs URLs by prefixing the path with
Server.getDefaultBaseUrl(), domain name and site name.
You can map multiple domain names to the same site. This is useful for covering top-level domains such as
.org and setting localized prefixes for sites like
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.
Magnolia 4.5.20 / Extended Templating Kit 2.0.21+ Request matcher rules can be configured in the module configuration.
ETKSiteManager matches content requests to a site in a multisite environment. Request matcher rules ensure that the correct content is served.
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/extended-templating-kit/config/rules should suffice in most environments.
class: Matcher class.
description: Describes what the configuration does.
multipleMatchesPossible: Whether the rule allows more than one match. When set to
false, if two site definitions match, the rule is bypassed.
info.magnolia.module.extendedtemplatingkit.sites.matchers.SiteNameMatcher: Checks the sitename (root node of the site in Pages).
info.magnolia.module.extendedtemplatingkit.sites.matchers.DomainMatcher: Checks the domains configured in the site definition.
info.magnolia.module.extendedtemplatingkit.sites.matchers.NotEmptyUriPrefixMatcher: Checks for a
URIPrefixproperty in the mappings node of the site definition.
info.magnolia.module.extendedtemplatingkit.sites.matchers.NotEmptyHandleMatcher: Checks for a handlePrefix property in the mappings node of the site definition.
info.magnolia.module.extendedtemplatingkit.sites.matchers.SiteHasEmptyUriPrefixMatcher: Checks for an empty URIPrefix property.
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 uses
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 uses
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 uses
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 uses
NotEmptyUriPrefixMatcher. Multiple matches possible.
handle-not-empty: Handle matches. Used for AdminCentral access. Singe-class rule uses
NotEmptyHandleMatcher. Multiple matches possible.
You can write your own custom matcher classes to create new rules.
The custom class should extend
AbstractMatcher that implements the
RequestMatcher interface. The interface matches requests (domain and URI) to a site. It returns an integer, minus is false, and positive is true. The return value of
@link #matches(String, String, info.magnolia.module.templatingkit.sites.Site) is used to filter the best matching request.
The first three examples demonstrate the default behavior. The last example provides a scenario where it is necessary to change it. You can replicate the examples on the demo sites. The examples assume you have mapped the domains to your system
hosts file and are working locally. Domains used are
Company A site renders because it is the best-matching site. The
uri-starts-with-sitename rule finds a match to the site name. No other rules are met.
Best practice is to always configure a site definition.
companyA site definition that extends
/domains/companyA/nameproperty set to
You can now request the Company A site at
domain-and-handle-not-empty rule is met. Both the domain and handle prefix match. The pop theme is applied by extension.
In the site definition created in the previous example, in
When you request
www.domain1.com:8080/magnoliaAuthor/ you are redirected to AdminCentral because the URI prefix is no longer empty. When you request
www.domain1.com:8080/magnoliaAuthor/investors, the Investors page renders as the
uri-prefix-not-empty rule is met.
In this example the default configuration does not serve the correct content and new rules need to be configured.
The use case could, for example, be a large corporation with a number of divisions. The corporation itself and each division has its own website and domain. Each site has a site definition that is mapped to the domain and root page (
The following site structures do not result in a conflict.
Top level site
Top level site
However when you add the subpages highlighted below the default rules no longer resolve all requests correctly because there is a URI conflict. Both sites have subpages with identical names to top-level sites.
When you request the Division A page on the Corporation site, the
/division-a site renders instead of the
/corporation/division-a page. When you request the Corporation page on the Division A site, the
/corporation site renders instead of the
/division-a/corporation page. This is because there is no configured rule to take account of the situation.
Here's the configuration to correct this behavior. The configuration replaces the default
uri-starts-with-sitename rule with the
domain-and-sitename rule that requires both the domain name and site name to match.
After configuring the new rule. the correct sites and subpages render.
Internationalization support is provided by
ETKI18nContentSupport. This class is configured in Configuration >
/server/i18n/content and it delegates to the i18n support configured in a site definition.
i18n configuration is typically in the
default site definition. Site-specific site definition can extend and override it. See Site definition > i18n for more about the
default configuration. In the
/demo-project-de definition the
defaultLocale is changed from
MultiSiteFilterinitializes the multi-domain support and makes domain related properties available in the aggregation state.
CrossSiteSecurityFilterdoes cross-site security checking based on the
SiteUriSecurityFilteris a site-aware URI security filter. For more information see Site-aware ACLs.
When content is published, the cache on the public instance is flushed to show the new content. This increases the load on the server and affects all sites in a multisite environment. You can configure multiple cache configurations to ensure that only cache entries that belong to the same subree (site) as the published content are flushed. See Multisite cache configuration for more.