Multisite

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.

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 name	Value
  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

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.

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.

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.

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:

• DomainNamePathTransformer constructs URLs by prefixing the path with Server.getDefaultBaseUrl() and domain name.
• CrossSiteAbsolutePathTransformer constructs 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 .net and .org and setting localized prefixes for sites like de.example.com, fr.example.com.

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.  Magnolia 5.2.6+ / Multisite 1.0.5+ and 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.

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.

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.

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.

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.  

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.

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.

Filters

• MultiSiteFilter initializes the multi-domain support and makes domain related properties available in the aggregation state.
• CrossSiteSecurityFilter does cross-site security checking based on the domainPattern. For more information see Cross-site security
• SiteUriSecurityFilter is a site-aware URI security filter. For more information see Site-aware ACLs.

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.