Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

Multisite support is an Enterprise Edition Pro feature provided by the Multisite 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 templates. Sites that are localized to the visitor's language or geographical area can inherit templates and themes from a parent site and add their own locales to support additional languages and country-specific domains.

Multisite requires an Enterprise Edition Pro license. You can create multiple site definitions also in EE Standard but you need an EE Pro license to unlock the multisite feature. With an EE Standard license, the system only takes the default site definition into account and will ignore additional site definitions.

If you do not need Multisite, remove the Multisite module jar from the bundle before you install Magnolia. Working with the Multisite module installed on EE Standard (running a single website) leads to logging errors. Due to module dependencies it is very difficult to uninstall the Multisite module once a website is running.

About site definitions

A site definition is responsible for assigning the following elements to a website:

  • Templates defines which page and component templates are available on the site.
  • Theme applies the visual look and feel. Themes consist of CSS, JavaScript and image variation rules.
  • Variations output content in various forms and formats.
  • i18n (internationalization) configuration allows you to serve sites in the visitor's language or geographical location.
  • Mappings identify where content for the site should be served from.
  • Domains allow branding and localization.

Default site definition

The default site definition is the fallback configuration for all sites and is the basis for site-specific definitions. It includes:

  • Template prototype configuration in /templates/prototype.
  • Page templates available on a global level in /templates/availability.
  • Assignment of the default pop theme in /theme.
  • Variation configurations in /variations.
  • Internationalization settings in /i18n.

    Node nameValue
     default 

     templates

     

     prototype

     

     availability

     

     theme

     

     name

    pop

     variations

     

     smartphone

     

     i18n

     

     locales

     

     en

     

     de

     

     class

    info.magnolia.cms.i18n.DefaultI18nContentSupport

     defaultLocale

    en

     enabled

    true

     fallbackLocale

    en

     label

    Default

Best practice

Always create a specific site definition and map it to your website. Don't rely on the default site definition alone. The default is a fallback site definition. It is not mapped to any particular site in the website workspace and it does not have a domain. You should at least specify URI-to-repository mappings and domain names in your specific site definition. However, you can extend the default to save effort.

Individual site definitions

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.

Node nameValue
 default 

 demo-project

 

 domains

 

 i18n

 

 mappings

 

 extends

../default

 demo-features

 

 domains

 

 i18n

 

 mappings

 

 extends

../default

 demo-project-de

 

 domains

 

 i18n

 

 extends

../demo-project

Here are a few suggestions that you can configure in an individual site definition:

  • A site-specific template prototype that change the navigation or creates new areas.
  • Make unique page and component templates available to editors.
  • Reference a unique theme.
  • Add site-specific CSS and JavaScript.

Mappings

The multisite feature uses Magnolia''s core  URI2RepositoryMapping (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 dam 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 dam workspace instead.

Node nameValue

 demo-project

 

 domains

 

 i18n

 

 mappings

 

 website

 

 URIPrefix

-

 handlePrefix

/demo-project

 repository

website

 extends

../default

 demo-features

 

 domains

 

 i18n

 

 mappings

 

 website

 

 URIPrefix

-

 handlePrefix

/demo-features

 repository

website

 extends

../default

handlePrefix

The 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 to /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 /demo-project/campaigns/winter2013. 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. In the same site definition you could configure a custom winter theme for the campaign and assign a vanity URL such as winter2013.example.com. Visitors who request the vanity URL are served content from /demo-project/campaigns/winter2013, not from the site root, and they see the campaign specific theme.

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 site hierarchy at /demo-project/marketing/campaigns/2013/winter. First set handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting URIPrefix to /winter2013. Visitors who request the URL www.example.com/winter2013 are served content from /demo-project/marketing/campaigns/2013/winter 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

 demo-project

 

 domains

 

 demo-project

 

 context

magnoliaPublic

 name

www.demo-project.com

 port

8080

 protocol

https

Properties:

  • context: Context path represents a web application such as magnoliaAuthor or 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:

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.  (warning) Magnolia 5.2.6+ / Multisite 1.0.5+ and (warning) Magnolia 5.3.2+ / Multisite 1.1.1+ 

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

 1

 

 class

info.magnolia.multisite.sites.matchers.AdminOnlyMatcher

 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:

  • <rule name>
    • matchers
      • <number>
        • 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. 

 

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.AdminOnlyMatcher: Checks the context (author or public), matches only on an author instance.
  • 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 uses DomainMatcher 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 uses DomainMatcher 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 uses DomainMatcher 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 uses NotEmptyUriPrefixMatcher.  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. 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.

Examples

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 www.domain1.com, www.domain2.com. www.corporation.com and www.division-a.com.

No site definition

  1. Set up a new site with the following structure:
    • /companyA
      • /about
      • /investors
      • /service
  2. Request www.demo-project.com:8080/magnoliaAuthor/companyA.

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.

(warning) Best practice is to always configure a site definition.

Domain and handle prefix

Configure a companyA site definition that extends /demo-project with:

  • /domains/companyA/name property set to www.domain1.com.
  • /mappings/website:
    • /repository set to website.
    • /handlePrefix set to /companyA.

You can now request the Company A site at www.domain1.com:8080/magnoliaAuthor/. The domain-and-handle-not-empty rule is met. Both the domain and handle prefix match. The pop theme is applied by extension.

Best practice

To avoid request matching conflicts give the site definition node, /domains/<node> node and the root page the same name. For example, name all three nodes companyA.

Domain and URI prefix

In the site definition created in the previous example, in /mappings/website:

  • Change /handlePrefix to /companyA/investors.
  • Set URIPrefix to /investors.

When you request www.domain1.com:8080/magnoliaAuthor/ you are redirected to the app launcher 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.

URI conflict

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 (handlePrefix).

The following site structures do not result in a conflict.

CorporationDivision

Top level site

  • /corporation
    • /about
    • /investors
    • /service

Top level site

  • /division-a
    • /about
    • /products
    • /service

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.

CorporationDivision

Top-level site

  • /corporation
    • /division-a
    • /about
    • /investors
    • /service

Top-level site

  • /division-a
    • /corporation
    • /about
    • /products
    • /service

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. 

Node nameDescription
 modules 

 multisite

 

 config

 

 rules

 

 domain-and-sitename

 

 matchers

 

 0

 

 class

info.magnolia.multisite.sites.matchers.DomainMatcher

 1

 

 class

info.magnolia.multisite.sites.matchers.SiteNameMatcher

 description

Domain and URI starts with site name: /<site-name>

 multipleMatchesPossible

false

 domain-and-handle-not-empty

 

 domain-and-site-uri-prefix-empty

 

 uri-prefix-not-empty

 

 handle-not-empty

 

After configuring the new rule. the correct sites and subpages render.  

 

i18n

Internationalization support is provided by info.magnolia.multisite.i18n.MultiSiteI18nContentSupport. This class is configured in the Configuration app > /server/i18n/content and it delegates to the i18n support configured in a site definition.

Node nameValue
 server 

 filters

 

 IPConfig

 

 i18n

 

 content

 

 class

info.magnolia.module.extendedtemplatingkit.i18n.ETKI18nContentSupport

 enabled

true

 system

 

 system

 

 authoring

 

A fallback 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 en to de.

Node nameValue
 default 

 templates

 

 themes

 

 variations

 

 i18n

 

 locales

 

 en

 

 de

 

 class

info.magnolia.cms.i18n.DefaultI18nContentSupport

 defaultLocale

en

 enabled

true

 fallbackLocale

en

 label

Default
 demo-project 
 demo-features 
 demo-project-de 

 domains

 

 i18n

 

 defaultLocale

de

 extends

../demo-project

Filters

The Multisite module provides three filters relevant to multisite support:

Cache

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.

  • No labels