Creating a custom theme

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.

Themes are configured in Templating Kit > 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, AdminCentral 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.

Registering a theme

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:

1. Go to Templating Kit > Themes:
2. Add a new content node and name it blue.
3. Under blue, add a data node extends and set its value to ../pop. This inherits all configuration from the pop theme.
4. Under 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.
5. Under 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.

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 Templating Kit > 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.

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 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;
}

Updating images

Images referenced by the pop theme in styles.css are also stored in 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.

Enterprise Edition:

1. Go to Templating Kit > Site Definition > /default/theme.
2. Set the value of the name property to blue.

Community Edition:

1. Go to Templating Kit > Site Configuration > /theme.
2. 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 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.

References

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

• WebDav module
• CMIS module

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

•  Resources
• Themes