Site definition

Site definitions enable you to individually control multiple websites, each with distinct domains and languages, within a single Magnolia installation. Each website corresponds to a website’s root page and its subpages in the Pages app.

The definition needs to be mapped to the website content. Specifically, you have to map your site definition to your website’s root page. The site definition and website must have the same name.

Additionally, every site definition can have its own site-wide theme and template prototype configurations. Template prototypes are used to define master page templates. Anything configured in them (for example, navigation, common page areas, or JavaScript) is applied to all page templates. Themes allow you to define different image renditions.

Go to the How to use Multisite section to configure multiple sites from one Magnolia installation.

Do I need a site definition?

No, it is not necessary to use a site definition. A site based on concrete template definitions works perfectly well. A site definition is an advanced option. It is useful when you have a large site and want to avoid repeating a similar configuration.

Without a site definition you can still:

  • Choose which templates are available to editors.

  • Add CSS and JavaScript at the page level instead of site level.

  • Configure variations for each page template.

But without a site definition you cannot use:

Prerequisites

You need the Site module in order to create a site definition. The Site module may not always be included, for example when you create your own webapp based on the empty webapp. Add a dependency to the Site module in your webapp POM file.

DX Core provides the multisite feature. It allows you to configure a different site definition for each website in a single Magnolia instance. Each site can be mapped to a different domain and you can serve content from different workspaces. These features are in the Multisite module.

Site limitation

In DX Core, the number of sites that can be used is defined by the number of sites purchased.

In the Community Edition, you can only create and use one site.

Configuring a site definition

You configure a site definition in <module_name>/sites/example.yaml. The site definition can be added to the sites folder of any light module. Go to the Definitions app to look at existing site definitions.

Mapping a site definition to your website

The mappings property defines exactly to which node a site definition applies. For example, in the mapping definition below, the root page /home-page is the website for which the site definition applies.

<module_name>/sites/home-page.yaml
...
mappings:
  website:
    URIPrefix: '' (1)
    handlePrefix: /home-page (2)
    repository: website
1 The URIPrefix maps a requested URL to one of the workspaces. For the website repository, it is always empty. See URI to repository mapping for more information.
2 The handlePrefix specifies the website to which the site definition is applied. The site definition and website must have the same name.

The URIPrefix defined in the site definition takes higher precedence over the system-wide configuration in the server config. Open the Configuation App, select the config workspace in JCR, and go to the node /server/URI2RepositoryMapping/mappings to see the general settings.

Some example mappings from the travel-demo are shown below. In addition to the website mapping, a mapping is set up for the dam repository. It maps the site definition to the /travel-assets folder in the dam repository, overriding the general /dam/ setting in URI2RepositoryMapping. URIPrefix and repository names must match those defined in Magnolia’s URI2RepositoryMapping.

domains:
  travel-demo:
    name: travel-demo.magnolia-cms.com

mappings:
  website:
    URIPrefix: ''
    handlePrefix: /travel
    repository: website

# Optional: The /dam/ mapping is rarely used. It is an example of a possible DAM mapping if needed.
  dam:
    URIPrefix: '/dam/'
    handlePrefix: /travel-assets
    repository: dam

Site definition properties

Property Description

templates

optional

     prototype

optional

The template prototype is a master template definition which applies to the whole site. Anything you configure in the prototype is applied to all page templates.

     availability

optional

Template availability defines which page templates are available to editors in the Pages app. There are more ways to control page template availability.

enabled

optional, default is true

Enables and disables the site definition.

domains

optional

Maps domain names to the site.

Requires the Multisite module (DX Core).

theme

optional

Reference to a theme that defines the look and feel of the site. Themes are configured in config:/site/config/themes.

i18n

optional

Locale configuration and support for entering and serving content in multiple languages.

For more details how to configure this i18n property subtree, see Defining locales for a site.

mappings

optional

URI mappings that define which node in a workspace should be served when a particular URI is requested.

trustedProxyConfig

optional

Configuration of a Trusted proxy headers filter for the given site.

travel
...
  trustedProxyConfig:
    forwardingEnabled: true
    headers:
      xForwardedFor:
        name: x_forwarded_for
        values:
          0: example.com
...

Incorrect filter configuration may block all user traffic.

If access to Magnolia is blocked by an incorrect filter configuration, you can fix this by decorating the site config and overriding the incorrect values.

Filter configuration parameters determine which headers are allowed or checked by this filter.

  • If forwardingEnabled is set to false (default), the filter blocks requests containing specific headers. This is to ensure security when proxy headers are not expected.

    The default setting prevents undesired traffic blocking.

  • If forwardingEnabled is set to true, the filter checks the values of specific headers in incoming requests. Requests with unexpected header values are blocked for security reasons.

Available header names:

  • x_forwarded_for for X-Forwarded-For

  • x_forwarded_host for X-Forwarded-Host

  • x_forwarded_proto for X-Forwarded-Proto

  • x_forwarded_port for X-Forwarded-Port

When using a proxy in front of Magnolia, it’s highly recommended to apply IP filtering in Tomcat so that only requests from the trusted proxy would be processed. For more details about setting IP filtering, see Remote Address Valve.

parameters

optional

Custom template properties that you can access from a script without having to write a class.

variations

optional

Variations adapt the site for different devices or geographical locations.

Configurations are stored here:

  • config:/modules/site/config/site and from any extended locations in a single-site setup (Community Edition, DX Core) * config:/modules/multisite/config/sites in a multisite setup (DX Core)

Example site configuration

Site configuration for the Travel Demo site that ships with Magnolia CE Demo. See below also how the site module configuration extends it.

/modules/travel-demo/config
travel:
  templates:
    class: info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings
    prototypeId: travel-demo:pages/prototype
    availability:
      templates:
        home:
          id: travel-demo:pages/home
        standard:
          id: travel-demo:pages/standard
        searchResultPage:
          id: travel-demo:pages/searchResultPage
        pur:
          id: travel-demo:pages/pur
        tour:
          id: tours:pages/tour
        categoryOverview:
          id: tours:pages/categoryOverview
        destinationCatOverview:
          id: tours:pages/destinationCatOverview
      enableAllWithRenderType:
        freemarker: freemarker
        spa: spa
  theme:
    name: travel-demo-theme
  i18n:
    class: info.magnolia.cms.i18n.DefaultI18nContentSupport
    enabled: true
    fallbackLocale: en
    locales:
      en:
        country:
        enabled: true
        language: en
      de:
        country:
        enabled: true
        language: de
  cors:
    travel:
      uris:
        rest:
          patternString: /.rest/*
      allowedOrigins:
        all: *
      allowedMethods:
        get: GET
      allowedHeaders:
        accept: Accept
        content-type: Content-Type
        origin: Origin
        x-pingother: X-PINGOTHER
        x-requested-with: X-Requested-With
/modules/site
config:
  site:
    extends: /modules/travel-demo/config/travel
...

Site definitions in CE and DX Core

The steps to create a site definition can vary depending on which modules you have installed. In Magnolia Community edition, you are only allowed a single site definition. For Magnolia DX Core, multiple site definitions are allowed. These instructions can be used as a guide for creating a new site definition from scratch.

Community Edition

When using Community edition, only the site module is installed. Therefore, you only have the option for a single definition as community edition can only support one site. Multiple sites would require multiple author instances or an upgrade to DX Core.

DX Core

When using DX Core, only the multisite module is installed. With the multisite module you can have as many sites as required. However, there are physical limits as each new site that is added creates additional complexity. It can sometimes be helpful to break installations into multiple author instances. Especially in cases where you have multiple different teams spanning different regions.

You can have as many author instances as you need as long as the content stays independent.
Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules