A theme's purpose is to give a site an unique look and feel with CSS and provide client-side functionality such as JavaScript effects.

• CSS
• Caching
• Processed resources
• JavaScript
• Theme as a module

Themes are defined in Templating Kit > Themes. They are assigned to site in the site definition.

Magnolia CMS ships with a theme called pop. It is a collection of CSS style sheets, Javascript and images variation rules that create the black and pink look you see on the demo-project and demo-features websites.

CSS

Cascading style sheets describe the presentation semantics (look and formatting) of an HTML document. Style sheets are configured in Templating Kit > Themes > /<theme_name>/cssFiles. Here's an example configuration for the pop theme.

An important features of style sheets is that they specify how a document is to be presented on different media: screen, paper etc. The cssFiles content node contains a collection of style sheets targeted at different media types.

• styles is a style sheet that optimizes the page layout for color computer screens and projected presentations. This is the most common style sheet, targeted at medium viewport sizes. When you visit the demo-project website with your desktop browser, this style sheet is most likely applied. The layout displays promos below the main content, see Medium in the table below.
• print is intended for printed documents and documents viewed in print preview mode. Print is a common use case of an alternative style sheet. When printing, navigation and ads are obvious candidates for hiding.
• wide optimizes the layout for wide screens. CSS media queries, introduced in CSS2, extend the functionality of media types by allowing more precise labeling of style sheets. A media query consists of a media type and expressions that check for width, height and color. By using media queries, presentations can be tailored to a specific range of output devices without changing the content itself. The query only screen and (min-width: 1200px) applies the wide style sheet when the browser viewport is at least 1200 pixels wide. Taking advantage of the new real estate, an additional promos sidebar is displayed on the right, see Wide in the table below.
• small optimizes the layout for narrow screens using media query only screen and (max-width: 980px). Now the main area displays two columns of teasers instead of three.

Wide: min. width 1200 px	Medium: 981 to 1199 px	Small: max. width 980 px

If you don't like this feature you can disable it by removing the wide and small configurations, making the layout static regardless of the viewport size.

The link property under the style sheet configuration points to the location of the actual CSS file. You can store style sheets in the resources workspace in the content repository. Go to Templating Kit > Resources > /templating-kit/themes/pop/css to see the files.

Caching

By default CSS files are cached far into the future by setting the farFutureCaching property to true. This instructs the browser to cache style sheets for one year. The idea is to keep resources such as CSS and JavaScript in the browser cache as long as possible. Serving them again at each page request would be inefficient and slow down the overall page download. For more on browser cache policy, see Cache module.

Processed resources

When a resource (CSS or JavaScript) is of type Processed, its content is interpreted as a FreeMarker template. You can use FreeMarker constants, variables and expressions inside the resource. You can also implement a custom model class and access the model's methods from inside the CSS or JavaScript document.

The model class is defined in the resource's properties dialog. You can use any Java logic or Magnolia functionality.

JavaScript

JavaScript is 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.

Magnolia uses jQuery to perform these actions. jQuery is a cross-browser JavaScript library designed to simplify client-side scripting of HTML. It supports DOM element selection, traversal and modification. The entire library is aggregated into a single JavaScript file in the resources workspace rather than embedded in the page HTML. An external file saves bandwidth by reducing page length, yielding faster downloads.

Like CSS, JavaScript is configured in a site definition. The jsFiles content node configures two scripts: all.js and init-behaviour.js. The first is the aggregate of all jQuery scripts, made available as one script. The second ships with the pop theme and is responsible for initializing teaser switching, embedded video player, animations in the FAQ paragraph, and other client-side functionality specific to this theme.

The script files are in the resources workspace. Go to Templating Kit > Resources > /templating-kit/js/all to see them. jQuery scripts are prefixed with jquery.

Like CSS, JavaScript can be of type Processed. You can use Freemarker expressions in the script as the system interprets it as a Freemarker template. Below is the parent script all.js that is provided. Freemarker's #list directive collects content from the child nodes which are individual jQuery scripts. The collected scripts are retrieved one-by-one and served as one long script.

/**
 * Aggregated script. All javascripts under this node will be included.
 */

var contextPath = '${contextPath}';
[#list content?children as subnode]
    ${mgnl.renderTemplate(subnode)}
[/#list]

Theme as a module

It is recommended that you create a dedicated module for your 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 and JavaScript from the module JAR into the resources workspace and images into the dms workspace. Once installed, you can reference the images with a relative URL such as ../img/example.gif in the CSS. This makes it easier for graphic designers to maintain files on their local file system while developing a theme. They can work outside of Magnolia CMS using their own tools and methods. When the theme is deployed to Magnolia CMS, virtual URI mapping resolves links to images automatically.