Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
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.
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,.
Themes are configured in Templating Kit > Themes.
pop theme has four nodes:
resourcesworkspace. Learn more about CSS in themes.
pop theme. To learn more about the inheritance mechanism, see .
To register a theme:
blue, add a data node
extendsand set its value to
../pop. This inherits all configuration from the
blue, add a content node
cssFilesand under it a content node
styles. This node structure is identical to the one in the
poptheme, it overrides the
styles, add data node
linkand set its value to
/resources/templating-kit/themes/blue/css/styles.css. You will create the CSS file in Creating a style sheet below.
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:
css, create a new node
stylesand set its type to Processed CSS.
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
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:
styles.csssheet and and click Edit Item.
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 component which renders a chronologically ordered list of upcoming events. The blue box with the date is the
The style definition for the
div.date element looks like this. Notice the background and border colors.
Images referenced by the
pop theme in
styles.css are also stored in Resources
To upload the image files:
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:
A theme is assigned to a site in a
blue theme to a site.
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 Magnolia wiki.
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.
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.
The resources available in Templating Kit > Resources can be accessed using Magnolia’s:
For more information on how resources are used in the STK, see: