Site module

Developer productivity Bundled: Community edition

Edition

CE

License

MLA, GPL

Issues

MGNLSITE

Git

Git

Maven site

Site

Latest

2.0.1

The Site module provides a site API. It allows you to create a site definition that contains configuration for a whole site such as navigation and common page areas.

Modules

Magnolia’s Site module reactor consists of the following submodules:

  • Site

  • Site Themes

  • Site JCR

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.site</groupId>
  <artifactId>magnolia-site</artifactId>
  <version>2.0.1</version>
</dependency>
<dependency>
  <groupId>info.magnolia.site</groupId>
  <artifactId>magnolia-site-themes</artifactId>
  <version>2.0.1</version>
</dependency>
<dependency>
  <groupId>info.magnolia.site</groupId>
  <artifactId>magnolia-site-jcr</artifactId>
  <version>2.0.1</version>
</dependency>

Configuration

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 the editors using 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.

theme

optional

Reference to a theme that defines the look and feel of the site.

i18n

optional

Node containing a locale configuration, with which you can add support for entering and serving content in multiple languages in your project.

For the properties configurable under the i18n node, see the separate i18n node properties table below.

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 aren’t 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.

cors

optional

A CORS configuration for the site definition.

For configuration details, see Request processing and filters: Properties.

i18n node

Properties

Property Description

enabled

optional, default is false

Enables support for localized content. Used to rewrite URIs and getting nodes based on the current language.

class

required

Class that implements info.magnolia.cms.i18n.I18nContentSupport such as:

  • Implementations for a site organized into a single tree, in which the locale prefix usually points to the root of a site.

    • info.magnolia.cms.i18n.IetfI18nContentSupport. This is the default implementation, which supports the IETF BCP 47 language Tags.

      Example
      i18n:
  enabled: true
  class: info.magnolia.cms.i18n.IetfI18nContentSupport
  fallbackLocale: en
  defaultLocale: cs
  locales:
    cz:
      languageTag: cs-CZ
      enabled: true

    • info.magnolia.cms.i18n.DefaultI18nContentSupport, which supports a language prefix such as /en/* in the URL and stores localized content in a node using the naming pattern <name>_<locale>, for example subtitle_en.

      Use this implementation if your site is organized into a single tree, in which the locale prefix usually points to the root of a site.

  • info.magnolia.cms.i18n.HierarchyBasedI18nContentSupport, which stores and serves localized content in a hierarchical structure.

    Use this implementation if your site is organized into multiple trees, in which site roots are usually named after the locales.

  • info.magnolia.cms.i18n.RequestLocaleAwareI18nContentSupport, which reads the locale from the request.

    This implementation doesn’t render language-specific URLs.

fallbackLocale

optional, default is en

Content is served for the fallback locale if content is not available for the current locale.

defaultLocale

optional

If no locale can be determined, the default locale will be set. If no default locale is defined, the fallback locale is used.

locales

required

     <locale>

required

An arbitrary locale ID. For example, one that consists of language and country such as zh-TW (for traditional Chinese) or pt-BR (for Brazilian Portuguese).

         country

optional, for configurations using the language property

Country code, such as BR for Brazil.

         language

required, unless a configuration with the languageTag property is used

Language code such as pt for Portuguese. See also Oracle: JDK 17 Supported Locales.

         languageTag

required, unless a configuration with the language property is used

An IETF BCP 47 language tag.

         enabled

optional, default is false

Enables the locale.

Usage

See Site definition.

Feedback

DX Core

×

Location

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

You are currently perusing through the Site module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules