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.
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 Templating Kit > Themes.
The default pop
theme has four nodes:
resources
workspace. Learn more about CSS in themes.resources
workspace.Registering a theme means making it available to sites. Themes are registered in Templating Kit > 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:
blue
.blue
, add a data node extends
and set its value to ../pop
. This inherits all configuration from the pop
theme.blue
, add a content node cssFiles
and under it a content node styles
. This node structure is identical to the one in the pop
theme, it overrides the pop
configuration.styles
, add data node link
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.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:
/templating-kit/themes/blue/css
.css
, create a new node styles
and 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 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:
styles.css
sheet 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 stkTeaserEventsList component which renders a chronologically ordered list of upcoming events. The blue box with the date is the div.date
element.
The style definition for the div.date
element looks like this. Notice the background and border colors.
div.date { position: absolute; top: 0; left: 0; margin: 0 5px 0 0; background: #d5edfe; border: 1px solid #abdbfe; width: 4em; }
Images referenced by the pop
theme in styles.css
are also stored in Resources /templating-kit/themes/pop/img
.
/templating-kit/themes/blue/img/bgs
and /templating-kit/themes/blue/img/icons
.To upload the image files:
binary
.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) }
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.
Enterprise Edition:
/default/theme
.name
property to blue
.Community Edition:
/theme
.name
property to blue
.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.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE module SYSTEM "module.dtd"> <module> <name>theme-pop</name> <displayName>Magnolia Pop Theme Module</displayName> <description></description> <versionHandler>info.magnolia.themes.pop.setup.PopThemeVersionHandler </versionHandler> <version>1.4.2</version> <properties> <property> <name>themeName</name> <value>pop</value> </property> </properties>
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.
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: