Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

In this article, we take you through the process of creating a new theme. Rather than starting from scratch, we adapt the pop theme that ships with Magnolia. The changes are limited to editing a single CSS file which controls the visual identity of the site. The purpose is to demonstrate how to create a new look and feel with minor changes.

About themes

A theme's purpose is to give a site unique look and feel and provide client-side functionality such as JavaScript effects. Magnolia ships with a theme called pop. It creates the black and pink look you see on the demo-project and demo-features websites.

In this exercise we will change the theme's primary colors to white and blue.

You are not limited to changing the visual appearance. The Standard Templating Kit is a framework that allows you to customize page layouts too. After you learn about themes, see what STK can do.

Themes are configured in STK > Themes.

The default pop theme has four nodes:

  • cssFiles contains links to the cascading style sheets which describe the presentation semantics (look and formatting). The actual CSS files are stored in the resources workspace. Learn more about CSS in themes.
  • jsFiles references JavaScript responsible for client-side functionality such as teaser paging, AJAX, menu animations, trees, embedded video player, mouse wheel support, Google Analytics and much more. JavaScript files are also stored in the resources workspace.
  • imaging contains rules for image variations. See the Imaging module  for more information.
  • bodyClassResolver registers the class that determines the page layout variations.

    Node nameValue











Registering a theme

Registering a theme means making it available to sites. Themes are registered in STK > Themes. Since this exercise is limited to changing the CSS, you only need to configure a new CSS and inherit everything else (JavaScript, images, layout variations) from the pop theme. To learn more about the inheritance mechanism, see Extending configuration.

To register a theme:

  1. Go to STK > Themes:
  2. Add a new node and name it blue.
  3. Under blue, add an extends property and set its value to ../pop. This inherits all configuration from the pop theme.
  4. Under blue, add a node cssFiles and under it a node styles. This node structure is identical to the one in the pop theme, it overrides the pop configuration.
  5. Under styles, add a link property and set its value to /resources/templating-kit/themes/blue/css/styles.css. You will create the CSS file in Creating a style sheet below.

    Node nameValue












    only screen and (min-device-width: 481px)



























Creating a style sheet

Customize the CSS that defines the visual identity of the site. The primary style sheet is styles.css. It defines fonts, colors, links, grid, layout and branding for all possible page templates, and references template images.

To add a new CSS file:

  1. Go to STK > Resources.
  2. Create folders /templating-kit/themes/blue/css.
  3. Under css, create a new node styles and set its type to Processed CSS.

Editing the styles

The fonts, colors, links, grid, layout and branding of all possible variations of a web page are defined in styles.css. Any image assets are also referenced. Reliance on this single CSS file allows you to change the look and feel of a site without touching the templates themselves. The images used by the pop theme are also stored in the resources workspace.

It is not strictly necessary to store this or any CSS file in the resources workspace. You can point to any valid internal or external URL. However, storing the file in the repository makes deployment and dependency management easier.

To edit styles:

  1. Select the styles.css sheet and and click Edit Item.
  2. Copy the Blue Theme style from our SVN repository and paste it into the sheet.
  3. Save.

You can diff the Blue CSS and the Pop CSS to find exactly where the changes are. They are mainly color swaps and links to background images. Here is an example of the stkTeaserEventsList component which renders a chronologically ordered list of upcoming events. The blue box with the date is the element.

The style definition for the element looks like this. Notice the background and border colors. {
   position: absolute;
   top: 0;
   left: 0;
   margin: 0 5px 0 0;
   background: #d5edfe;
   border: 1px solid #abdbfe;
   width: 4em;

Updating images

Images referenced by the pop theme in styles.css are also stored in STK > Resources /templating-kit/themes/pop/img.

  1. Create folders /templating-kit/themes/blue/img/bgs and /templating-kit/themes/blue/img/icons.
  2. Download Blue Theme images from SVN and upload them into the folders.

To upload the image files:

  1. Create a new item of resource type binary.
  2. Click Edit Item.
  3. Upload the image.
  4. Save.

Images are referenced with a relative URL and can have the same file names as the pop theme images. Magnolia handles mapping the URLs. For example:

#extras .toc-box .toc-box-section {
   background: #f2f2f2 url(../img/bgs/text-box-220.png)

Assign the theme to a site

A theme is assigned to a site in a site definition. This is the only part where procedures between the Enterprise and Community editions differ. The Enterprise Edition supports multiple sites, each with an individual theme, whereas the Community Edition only supports a single theme. Here you assign the blue theme to a site.

Go to STK > Site Definitions:

  • Enterprise Edition: In /default/theme set the value of the name property to blue.
  • Community Edition: In /theme set the value of the name property to blue.

Theme as a module

It is recommended that you create a dedicated module for your own theme. This way you can decouple presentation logic from content and functionality. You only need to touch the theme module when the theme actually changes. This simplifies the deployment cycle too as you only need to deploy the theme if it changes.

To create a theme module, copy the structure of module-theme-pop and follow the Module Quickstart article on the wiki or the Setting up projects and modules unit of Magnolia academy.

The module descriptor in META-INF/magnolia/theme-<themeName>.xml defines a version handler. A theme module should use or extend the  ThemeVersionHandler class. Theme modules also have a themeName property in the module descriptor.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "module.dtd">
  <displayName>Magnolia Pop Theme Module</displayName>

ThemeInstallTask is the task that installs CSS, JavaScript and images from the module JAR into the resources workspace.

Theme specific configuration is bootstrapped into the config workspace. It is important to use the following location and filename within your module JAR for the bootstrap file: /mgnl-bootstrap/theme-<themeName>/config.modules.standard-templating-kit.config.themes.<themeName>.xml. Note especially the theme- prefix in the folder name.

When creating a new theme avoid using the same name for files and folders, for example a folder named myTheme and a CSS file named myTheme.css, because could potentially cause issues when a new theme module is imported into the STK.

(warning) Magnolia 5.3.2+/STK 2.8.2+ and (warning) Magnolia 5.2.6+ /STK 2.7.6+ Introduces the ability to install theme images with the same name, but different extensions, for example icon.jpg and icon.gif ThemeInstallTask calls two new task classes, InstallTextResourcesTask and InstallBinaryResourcesTask, that support a stripExtension parameter that is set to false. Create a custom version handler to enable the feature by subclassing ThemeVersionHandler and ThemeInstallTask.


The resources available in STK > Resources can be accessed using Magnolia’s:

For more information on how resources are used in the STK, see: