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 STK > Themes.
pop theme has four nodes:
cssFilescontains links to the cascading style sheets which describe the presentation semantics (look and formatting). The actual CSS files are stored in the
resourcesworkspace. Learn more about CSS in themes.
imagingcontains rules for image variations. See the for more information.
bodyClassResolverregisters the class that determines the page layout variations.
Node name Value
Registering a theme
pop theme. To learn more about the inheritance mechanism, see .
To register a theme:
- Go to STK > Themes:
- Add a new node and name it
blue, add an
extendsproperty and set its value to
../pop. This inherits all configuration from the
blue, add a node
cssFilesand under it a node
styles. This node structure is identical to the one in the
poptheme, it overrides the
styles, add a
linkproperty 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 name Value
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:
- Go to STK > Resources.
- Create folders
css, create a new node
stylesand 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
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:
- Select the
styles.csssheet and and click Edit Item.
- Copy the Blue Theme style from our SVN repository and paste it into the sheet.
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 STK > Resources
- Create folders
- Download Blue Theme images from SVN and upload them into the folders.
To upload the image files:
- Create a new item of resource type
- Click Edit Item.
- Upload the image.
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:
Assign the theme to a site
A theme is assigned to a site in a 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/themeset the value of the
- Community Edition: In
/themeset the value of the
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.
The module descriptor in
META-INF/magnolia/theme-<themeName>.xml defines a version handler. A theme module should use or extend the
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.
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
css, because could potentially cause issues when a new theme module is imported into the STK.
Magnolia 5.3.2+/STK 2.8.2+ and Magnolia 5.2.6+ /STK 2.7.6+ Introduces the ability to install theme images with the same name, but different extensions, for example
calls two new task classes,
InstallBinaryResourcesTask, that support a
stripExtension parameter that is set to
false. Create a custom version handler to enable the feature by subclassing
The resources available in STK > Resources can be accessed using Magnolia’s:
For more information on how resources are used in the STK, see: