A site definition contains site-wide configuration such as navigation, common page areas, and JavaScript that you want to load on every page. A site definition also contains a reference to your theme and defines locales for entering content in multiple languages.

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 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 bundle based on the empty webappAdd a dependency to the Site module in your webapp pom file.

Enterprise Edition Pro 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.

Edition limitations

  • Community Edition allows one site definition
  • Enterprise Edition Standard allows one site definition
  • Enterprise Edition Pro allows unlimited site definitions

Configuring a site definition

Configure a site definition in the Site app.

Example: Site definition for the Travel Demo site that ships with Magnolia (partial example).

Node nameValue

 travel

 

 templates

 

 availability

 

 templates

 

 home

 

 id

travel-demo:pages/home

 prototype

 

 areas

 

 navigation

 

 footer

 

 main

 

 jsFiles

 

 theme

 

 name

travel-demo-theme

 i18n

 

 class

info.magnolia.cms.i18n.DefaultI18nContentSupport

 enabled

true

 locales

 

 en

 

 country

 

 enabled

true

 language

en

 de

 

Nodes and properties:

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 (EE Pro).

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.

When configuring the i18n node, make sure to provide the properties class and enabled.

class

required (when using i18n)

For instance use info.magnolia.ui.framework.i18n.DefaultI18NAuthoringSupport.

enabled

optional , default is false
mappings

optional

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

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.

The Site app is actually a shortcut that displays the configuration from:

  • config:/modules/site/config/site and from any extended locations in a single-site setup (Community Edition, Enterprise Edition Standard)
  • config:/modules/multisite/config/sites in a multisite setup (Enterprise Edition Pro)

Choosing a fallback site definition

fallback is a special site definition that is used when no site matches the request. Think of it as a "default".

When you have multiple sites, configure one of them as a fallback. Use the  extends property to reference a complete site definition. 

Example: Choosing travel as a fallback site definition in /modules/multisite/config/sites  

Node nameValue

 fallback

 

 extends

../travel

 travel

 

 sportstation

 
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))