Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

A theme gives the site its visual identity through the use of images, colors and typography. A theme consists of Cascading Style Sheets (CSS), Javascript files, template images and an imaging configuration which tells the Imaging module how to resize and crop images for a particular page or component. The STK ships with two default themes:

  • pop the black and pink look that you see in the demo-project and demo-features websites.
  • pop-mobile the black and blue look you see in the the smartphone variation.

 

STK themes comply with the principles of Responsive Web Design, but Magnolia can be configured to adapt to all design approaches. See the Responsive Web Design article for more information.

Assignment

Themes are assigned in the site definition. The default pop theme is assigned in Site Definitions > /default/theme/name and the pop-mobile theme in /default/variations/smartphone/theme/name.

For more information on the pop-mobile theme see the Mobile page.

Configuration

Themes are configured in Templating Kit > Themes. The four configuration nodes define the individual elements of a theme:

  • cssFiles defines links to style sheets that you can access in Templating Kit > Resources.
  • jsFiles defines links to JavaScripts that you can access in Templating Kit > Resources.
  • imaging defines image variations for the various renditions of an image on the page.
  • bodyClassResolver registers the BodyClassResolver class that resolvers the bodyClass of the page. See Body classes for more information.

Resource loading

CSS sheets and JavaScripts are included in the <head> element of the HTML code. The htmlHeader area definition in the template prototype in Templating Kit > Site Definitions /default/templates/prototype/templates/areas/htmlHeader references the htmlHeader.ftl script that ensures that appropriate resources are loaded on the page. For more information see htmlHeader area.

STK resources are stored in the resources workspace. Resources can be loaded from three sources: the classpath, file system or resources workspace. See Resources loading for more information.

Far future caching

Far future caching enhances performance and page load times by caching resources one year into the future.
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 .

CSS

Cascading style sheets describe the presentation semantics of an HTML document, and create the look and feel of the site.

The Themes > /<theme name>/cssFiles node links the style sheets of the theme. The pop theme uses numerous sheets and the pop-mobile theme uses a single sheet. Each sheet is configured in its own child node that can have an arbitrary name. A number of properties are available:

  • farFutureCaching set to true instructs the browser to cache style sheets for one year.
  • link defines the path to the CSS file.
  • media defines the media query associated with the linked CSS file. See CSS Media queries for more information.
  • conditionalComment defines the conditional comment attribute associated with the linked CSS file. Conditional comments are used to overcome the limitations of legacy browsers. The ie6 and iestyles configuration nodes use this attribute. The statement is interpreted by Microsoft Internet Explorer and Magnolia uses them to provide and hide code to and from Internet Explorer.

The cssFiles child content nodes link to a collection of style sheets targeted at different media types. With one exception, the content nodes and linked <file name.css> have the same names:

Node

Description

styles

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.

print

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

Wide optimizes the layout for wide screens. CSS media queries, introduced in CSS2, extend the functionality of media types by allowing more precise labelling 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.

small

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.

mobile

Mobile optimizes the layout for handheld devices using media query only screen and (max-device-width: 480px). See Mobile for more information about the mobile-specific pop-mobile theme.

ieStyles

Uses the styles.css sheet that applies conditional comments to overcome IE7 & IE8 media query limitations.

ie6

ie6 is a specialized CSS only used for IE6 clients.

When the browser viewport changes to wider or narrower, the appropriate alternative style sheet is applied. The default layout of three fixed columns is optimized for medium screens. On wide screens the promos move to the right. On small screens the number of columns is limited to two.

You can disable this feature 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.

Template images

The template images referenced by the CSS files are stored in the resources workspace. Go to Templating Kit > Resources templating-kit/themes/<theme-name>/img to view them.

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.

As with CSS, JavaScript is configured in the theme configuration. The jsFiles content node configures three scripts: scriptloader-libraries.js, scriptloader-plugin.js and init-behaviour.js. The first two are aggregator scripts that make the library and plugin jQuery scripts available as a single script. The third 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 and /templating-kit/themes/pop/js to see them. The files are organized in folders for better maintenance, exchangeability and flexibility.

Aggregator scripts

The aggregator scripts contain reference scripts. A reference script points to a physical JavaScript within the resources configuration and uses a specialized renderer, ReferenceResourceRenderer. When rendering a reference script, the renderer renders the content of the referenced target script as if it were physical content. With this mechanism it is possible to reference any JavaScript located within the folders and trigger its rendering as if it was a part of the aggregator script. New JavaScripts or packages can be added to the right aggregator script with ease.

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 aggregator script scriptloader-plugin.js that is provided. Note that Freemarker's #list directive collects content from the referenced scripts.

[#list cmsfn.children(content) as child ]
    [@cms.component content=child /]
[/#list]

Image variations

A variation is an STK specific configuration that defines the size of the target image and tells the imaging engine whether cropping is allowed. Variations are configured in a theme rather than under the Imaging module's config node. This way you can configure image look and feel aspects in the same place as CSS.

STK variations are implemented as an image operation chain in /modules/imaging/config/generators/stk. You can add your own operations to this chain. Be aware that any operations you add apply to all STK images. For example, if you configure a custom text overlay, the overlay will be added to all STK images.

Here is an example variation promo that creates 218 x 162 pixel images for use in stkPromo components. Promos are elements that promote topical content such as campaigns, news or offers. They are displayed on the right or below the main content depending on your viewport size.

This is what a promo element looks like on the page.

Variations consist of the following properties.

Property

Value

/variation name

Content node that contains the variation.

  /rule

Content node that contains CSS selectors.

    cssSelector

Standard CSS selector that identifies the target image or containing element on page. Value can be a class (.teaser), ID (#main) or both (#main .vcard).

  width

Target width of the image in pixels. You must specify either width or height or both. If you don't specify either the engine will not generate an image.

  height

Target height of the image in pixels.

  crop

Determines whether cropping is allowed. (optional) Possible values are true (default) and false. When true, the image will be cropped symmetrically from both sides, focusing on the center. When false, the engine will resize the image to the smaller of the two target dimensions, constraining the aspect ratio.

The variation name is up to you. Pick a name that identifies the purpose of the target image such as teaser so it's easier to remember what it is used for.

Example 1: Article header

Article header is an example of a variation. In the demo-project, large images can be placed between the page title and abstract. In this example we look at how these images are resized using variation rules.

Source image files are stored in DMS folder /demo-project/img/bk/Opener. They are 613 x 384 JPG files. The Standard Article in /demo-project/about/subsection-articles/article/standard-article opens with an image of a coral light. Depending on where the editor wants to position the image - left, right or above the abstract text - component model TextImageModel assigns one or two CSS classes to the image element. When the image is positioned above the abstract, the CSS classes are photo and large. When the image is positioned to the left or to the right of the abstract, the CSS class is just photo.

Variation content defines a CSS selector that matches any page elements that have both classes photo and large. The width property in the variation instructs the imaging engine to create a 458 pixels wide image. Default value for crop is true so the engine is allowed to crop the image if needed to meet the target dimensions. Since no height is specified in the variation, the engine will keep the aspect ratio the same as the original image. No cropping is needed.

By inspecting the derivative image you can verify that it has the target width 458 pixels.

If the editor chooses to align the header image to the left or right of abstract instead, the component model assigns only the photo CSS class to the image. Variation rule content-small matches elements that have only this class and creates a smaller 218 pixels wide image instead.

Example 2: Teaser

A teaser is a special component that displays a small selection of a target page's content and invites the reader to read more. Here is a teaser used on the About page. It teases the Standard Article and uses the same image of a coral light as the article itself uses as an opener.

The image used in the teaser is a smaller variation of the source image. The teaser component belongs to a teaser group that consists of two teasers, each teasing a different article. The group's DIV element has a CSS class teaser-group. The teaser is a child element of the group, contained in a DIV teaser.

Variation teaser-in-group matches a teaser element nested in a teaser group with CSS selector .teaser-group .teaser. It instructs the imaging engine to create a 218 x 136 image, cropping if needed. See descendant selectors on how to use the space character to match a descendant element.

Disabling STK imaging support

In the STK imaging support is enabled in Templating Kit > Themes /<theme name>/imaging/enabled. To disable it for any theme set this property to false.

Customization

Variations are implemented as an image operation chain configured in Configuration > /modules/imaging/config/generators/stk. You can add your own operations to this chain. Be aware that any operations you add apply to all STK images. For example, if you configure a custom text overlay, the overlay will be added to all images. See the Imaging module for more information.

Creating a module for a theme

Creating a dedicated module for your theme decouples presentation logic from content and functionality. This simplifies the deployment cycle 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 Java 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>2.0.2</version>
  <properties>
    <property>
        <name>themeName</name>
        <value>pop</value>
    </property>
  </properties>

Theme install task

Theme resources are the CSS files, JavaScript files (init-behaviour scripts) and any images used by the CSS. The ThemeInstallTask installs resources into the resources workspace. The task is triggered by the ThemeVersionHandler. Resources are therefore installed automatically during theme install or upgrade.

Theme specific configuration is bootstrapped into the config workspace. 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.

STK resources that support themes

InstallSTKResourcesTask (Git) installs STK resources that themes depend on. They include the scriptloader libraries and plugins and their mobile equivalents and the init-behavior script. Since the STK takes care of them, your own theme does not need to install the files.

Adding a mobile project theme

In your project module you can add a mobile project theme the same way the pop-mobile theme complements the pop theme:

  1. Copy the pop-mobile theme configuration in Templating Kit > Themes /pop-mobile and adapt it to your project.
  2. Use your mobile.css within this configuration.
  3. Use the existing mobile mobile-scriptloader-libraries and mobile-scriptloader-plugin JavaScripts from STK.
  4. Create a init-mobile-behaviour.js script within your project module. The best way to start is with a copy of pop's init-mobile-behaviour.js. Adapt it to your project needs.

For more information about working with STK resources see the Resources page.

References

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

Related articles:

  • No labels