Themes

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 STK > 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 STK > Themes. The four configuration nodes define the individual elements of a theme:

• cssFiles defines links to style sheets that you can access in STK > Resources.
• jsFiles defines links to JavaScripts that you can access in STK > Resources.
• imaging defines image variations for the various renditions of an image on the page.

• bodyClassResolver registers the BodyClassResolver class that resolves the bodyClass of the page. See Body classes for more information.

  Node name
  pop
  cssFiles
  jsFiles
  imaging
  bodyClassResolver
  pop-mobile
  cssFiles
  jsFiles
  imaging
  bodyClassResolver

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 STK > Site Definitions /default/templates/prototype/areas/htmlHeader references the htmlHeader.ftl script that ensures that appropriate resources are loaded on the page. For more information see htmlHeader area.

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 STK > 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.

  Node name	Value
  pop
  cssFiles
  styles
  farFutureCaching	true
  link	/resources/templating-kit/themes/pop/css/styles.css
  media	only screen and (min-device-width: 481px)
  ie6
  ieStyles
  wide
  small
  mobile
  print
  jsFiles
  imaging
  bodyClassResolver
  pop-mobile
  cssFiles
  mobile
  farFutureCaching	true
  link	/resources/templating-kit/themes/pop/css/mobile.css
  media	screen

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:

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 STK > 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 STK > Resources /templating-kit/themes/<theme-name>/img to view them.

JavaScript

JavaScript is responsible for client-side functionality such as teaser paging, AJAX, 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 STK > 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 the Configuration app > /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.

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 the DAM app > /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.

Configuring an image operation chain

You can configure an image operation chain within a variation. See Imaging module for more information.

The example configuration below applies InvertFilter to the promo image variation. This filter inverts the RGB channels of an image. ImageOperationProvidingVariation provides STK support for the configuration options available when configuring image generators in the Imaging module

Here are example promos with the filter applied.

Disabling STK imaging support

In the STK imaging support is enabled in STK > 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 the Configuration app > /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 wiki or the Setting up projects and modules unit of Magnolia academy. 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>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.

Magnolia 5.3.2+/STK 2.8.2+ and Magnolia 5.2.6+/STK 2.7.6+: To install theme images that have the same name but different extensions, for example icon.jpg and icon.gif, use the InstallTextResourcesTask and set the stripExtension parameter to false. Create a custom version handler by subclassing ThemeVersionHandler and ThemeInstallTask. ThemeInstallTask calls InstallTextResourcesTask.

InstallTextResourcesTask(String taskName, String taskDescription, String encoding, String pattern, String template, boolean processed, String modelClass, boolean preserveResourcesParameters, boolean stripExtension)

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 STK > 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 STK > Resources can be accessed using Magnolia’s:

• WebDav module
• CMIS module

Related articles:

• Creating a custom theme
• Quick guide > Creating a new theme