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

A theme is a collection of resource files that gives a site its visual identity through the use of colors and typography. A theme consists of Cascading Style Sheets (CSS), Javascript files and an imaging configuration which tells the Imaging module what to do with images for a particular page or component.

What is a theme?

A theme is a module or part of a module composed of CSS, JS, and images.

When to use a theme

The Site module provides theme functionality. You can only create a theme if you use this module and have configured a site definition.

Themes and modules

Theme resources can be stored in light (YAML) or Maven modules. Themes can reside in a dedicated theme module or form part of another module. A special module version handler is not necessary.

Resource loading

All Magnolia resources, including theme resources, are loaded under the /.resources ("dot resources") path.

  • In a Maven module the resources are located in /src/main/resources/<moduleName> and any subfolder.
  • In a light module resources can be located any subfolder of your module, for example, /<moduleName>/webresources/

Theme resources can also be loaded from an external source by specifying the full URL. This is very useful if you use a CDN to store, cache and deliver your static resources.

See Resources and Module structure for more.

Benefits of using a theme

Themes offer a number of benefits:

  • Theme resources are applied to the entire site.
  • Resources are all in one place.
  • Themes are an easy way to work with resources without having to modify the head section of your HTML
  • You can define more than one theme and switch between them, or apply a different theme to a variation of your site. For example, you could use a different theme for pages targeted at U.S. users and European users, or a seasonal theme for different times of the year.
  • You can still use different or additional overriding resources on a page-template level.

Configuring a theme

Where to configure a theme

Themes can be configured:

  • In any module.
  • In YAML on the file system or in the JCR.

Proper location

The configuration must reside in the themes folder of the module in /<module-name>/themes/<theme-name>. This can be done in YAML or JCR.

Old location

The old and (warning) deprecated  location for themes is site/config/<theme-name>. Themes in this location could only be configured in the JCR.  Themes configured in the old location should be moved to the new location.

Example

travel-demo-theme in travel-demo/themes/travel-demo-theme.yaml.

travel-demo/themes/travel-demo-theme.yaml
cssFiles:
  #CSS files configuration
jsFiles:
  #JavaScript files configuration
imaging: 
  #Imaging variations configuration
Node name

 travel-demo-theme

 cssFiles

 jsFiles

 imaging

Three configuration nodes define the individual elements of a theme:

travel-demo-theme 

cssFiles

Optional

References CSS files.

jsFiles

Optional

References JavaScript files.

imaging

Optional

Defines image variations a.k.a renditions.

 

CSS files

Links to CSS resources are configured in the cssFiles node of the theme.

CSS defines the presentation semantics of an HTML document, and creates the look and feel of the site. 

Example: cssFiles configuration in travel-demo-theme in travel-demo/themes/travel-demo-theme.yaml.

travel-demo/themes/travel-demo-theme.yaml
cssFiles:
  bootstrap:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/twitterbootstrap/css/bootstrap.min.css
    media: all
  roboto-condensed:
    addFingerPrint: true
    link: https://fonts.googleapis.com/css?family=Roboto+Condensed:400,300,700
    media: all
  slick:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/slick-carousel/css/slick.css
    media: all
  slick-theme:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/slick-carousel/css/slick-theme.css
    media: all
  travels-magnolia:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/css/travels-magnolia.css
    media: all
  video:
    addFingerPrint: true
    link: /.resources/mtk/css/video.css
    media: all
jsFiles:
  #JavaScript files configuration
imaging: 
  #Imaging variations configuration
Node nameValue

 my-theme

 

 cssFiles

 

 bootstrap

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/twitterbootstrap/css/bootstrap.min.css

 media

all

 roboto-condensed

 

 addFingerPrint

true

 link

https://fonts.googleapis.com/css?family=Roboto+Condensed:400,300,700

 media

all

 slick

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/slick-carousel/css/slick.css

 media

all

 slick-theme

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/slick-carousel/css/slick-theme.css

 media

all

 travels-magnolia

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/css/travels-magnolia.css

 media

all

 video

 

 addFingerPrint

true

 link

/.resources/mtk/css/video.css

 media

all

 

Properties:

cssFiles

optional

CSS node of the theme.

<name>

required

Arbitrary node name. Add a node for each sheet.

addFingerPrint

optional

Embeds a file content fingerprint in the resource URL. The fingerprint consists of a timestamp in the yyyy-MM-dd-HH-mm-ss-SSS format and the word "cache" both preceded by the the standard selector ("~" tilde). For example the travels-magnolia link (above) becomes  /.resources/travel-demo-theme/css/travels-magnolia~2015-08-16-09-49-00-000~cache.css. Google recommends fingerprinting as a best practice.

link

required

Path to the CSS file that is added to the HTML. See Adding style to HTML for more. See also Web resources and Origins and loading order for different options for storing and loading resources.

media

optional

conditionalComment

optional

Defines the conditional comment attribute for the linked CSS file. Conditional comments are used to overcome the limitations of legacy browsers such as Internet Explorer 9 and earlier. For example, the conditional comment  "lte IE9" would be translated to:

<!--[if lte IE9]>
	//inclusion of the stylesheet or javascript resource
<![endif]-->

This simple theme example uses only the default Bootstrap minimized CSS with no customizations.

JavaScript files

Links to JavaScripts are configured in the jsFiles node of the theme.

JavaScript is responsible for client-side functionality such as carousel paging, AJAX, menu animations, trees, embedded video player, mouse wheel support, Google Analytics and much more.

Example: jsFiles configuration in travel-demo-theme in travel-demo/themes/travel-demo-theme.yaml.

travel-demo/themes/travel-demo-theme.yaml
cssFiles:
  #CSS files configuration
jsFiles:
  respimage:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/lazysizes/respimage.min.js
  lazysizes:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/lazysizes/lazysizes.min.js
  modernizr:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/js/modernizr-2.6.2.min.js
  jquery:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/js/jquery-1.10.2.min.js
  js.cookies:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/js/js.cookies-2.1.2.js
  jquery.object-fit-cover-simple:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/js/jquery.object-fit-cover-simple.js
  slick:
    addFingerPrint: true
    link: /.resources/travel-demo-theme/libs/slick-carousel/js/slick.min.js
  addtoany:
    link: https://static.addtoany.com/menu/page.js
imaging: 
  #Imaging variations configuration
Node nameValue

 my-theme

 

 jsFiles

 

 respimage

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/lazysizes/respimage.min.js 

 lazysizes:

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/lazysizes/lazysizes.min.js

 modernizr

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/js/modernizr-2.6.2.min.js 

 jquery

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/js/jquery-1.10.2.min.js

 js.cookies

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/js/js.cookies-2.1.2.js 

 jquery.object-fit-cover-simple

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/js/jquery.object-fit-cover-simple.js 

 slick

 

 addFingerPrint

true

 link

/.resources/travel-demo-theme/libs/slick-carousel/js/slick.min.js 

 addtoany

 

 link

https://static.addtoany.com/menu/page.js


Properties:

jsFiles

optional

JavaScript node of the theme.

<name>

required

Arbitrary node name. Add a node for each JavaScript file.

addFingerPrint

optional

Embeds a file content fingerprint in the resource URL. The fingerprint consists of a timestamp in the yyyy-MM-dd-HH-mm-ss-SSS format, and the word "cache" both preceded by the the standard selector ("~" tilde). For example the modernizer link (above) becomes  /.resources/travel-demo-theme/js//modernizr-2.6.2.min~2015-08-16-09-49-00-000~cache.css. Google recommends fingerprinting as a best practice.

link

required

Path to the JavaScript file. See Web resources and Origins and loading order for different options for storing and loading resources.

Here's an example JavaScript alert box using JQuery and the default Bootstrap minimized CSS.

Image variations

Themes can make use of the Imaging module to preconfigure image variations. A variation is a specific configuration that defines features of a target image. Variations can range from complex operations, such as applying filters and overlays, to simple resizing of the target image. 

Variations are an effective alternative to resizing images with CSS:

  • Image size is reduced and less data transferred.
  • Editors can upload images of any size which will automatically be resized to fit the template.
  • Image sizes are uniform throughout the site.

Variations are configured in the imaging node of the theme.

Example: imaging configuration in travel-demo-theme in travel-demo/themes/travel-demo-theme.yaml.

travel-demo/themes/travel-demo-theme.yaml
cssFiles:
  #CSS files configuration
jsFiles:
  #JavaScript files configuration
imaging:
  class: info.magnolia.templating.imaging.VariationAwareImagingSupport
  variations:
    "1600":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 1600
    "1366":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 1366
    #......
    "240":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 240
    "1600x1200":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      height: 1200
      width: 1600
    "1366x1024":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      height: 1024
      width: 1366
    #.....
    "240x180":
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      height: 180
      width: 240
Node nameValue

  travel-demo-theme

 

 imaging

 

 variations

 

 1600

 

  class

info.magnolia.templating.imaging.variation.SimpleResizeVariation

  width

1600

 1366

 

 ...

 

 240

 

 1600x1200

 

  class

info.magnolia.templating.imaging.variation.SimpleResizeVariation

  height

1200

 width 

1600

 1366x1024

 

 ...

 

 240x180

 

  class

info.magnolia.templating.imaging.VariationAwareImagingSupport


Properties:

imaging

optional

Imaging node of the theme.

variations

required

Image variations node.

<variation>

required

The name of the variation, a.k.a the rendition name. The name is used to call the variation in template scripts. Add one node for every variation.

class

required

You can use one of the available classes or create a custom one. The available properties depend on the class used for the variation. Any custom class must implement Variation.

MTE module provides SimpleResizeVariation that resizes images to a defined size in pixels (see below for available properties).

<properties>

Add properties that are supported by the class used.

class

required

VariationAwareImagingSupport provides support for variations.

enabled

optional

Enables and disables variation support.

Configuring a simple resize

The SimpleResizeVariation class is suitable for most resize variations. It resizes the original image to a defined size in pixels.

Properties:

<variation name> 

class

required

SimpleResizeVariation resizes images to a defined size.

crop

optional, default is true

Whether cropping is allowed.

height

optional

An integer that defines the height in pixels.

width

optional

An integer that defines the width in pixels.

Behavior:

  • Although both the width and height properties are optional you must configure at least one. If you omit both the renderer intentionally throws an internal ImagingException and the image displays in it's original uploaded size.
  • If you define both width and height the image is sized down to the lower of the two and the rest is cropped, if necessary. Cropping starts from the middle, so the image is either cropped on top and bottom, or left and right.
  • If you define only width or height, the omitted property is calculated using the aspect ratio of the original image.
  • if you set crop to false, the image is resized to the specified size, and may be distorted (stretched).

See damfn and Working with images using damfn for how to use variations in your scripts.

Assigning a theme to a site

Themes are assigned to a site in the theme node of the site definition in the Site app

Example: Travel Demo Site Definition (CE)

Node nameValue

 templates

 

 themes

 

 name

travel-demo-theme

 i18n

 

Properties:

themes

required

Theme node.

name

required

The value of this property must match the name of the theme configured in /modules/site/config/themes.

Using theme resources in template scripts

Theme resources are typically added to the <head> element of a page template.

  • Retrieve the configured theme configured over the sitefn function class:

    [#assign site =
    sitefn.site()!]
    
    [#assign theme =
    sitefn.theme(site)!]
  • Iterate over the theme configuration and include the configured resources:

    [#list theme.cssFiles as cssFile] 
        <link rel="stylesheet" href="${cssFile.link}" media="${cssFile.media}" />
    [/#list]
    
    [#list theme.jsFiles as jsFile]
        <script src="${jsFile.link}"></script>
    [/#list]

Viewing and editing themes

Theme definitions from all sources and origins are available in the Definitions app. Select theme in Of type to find all theme definitions. You can hotfix themes in the Resource Files app. Select the theme definition and click Show in Resources in the Definitions app to access the file. 

Example: travel-demo-theme in Definitions app and Resource files app.