popthe black and pink look that you see in the demo-project and demo-features websites.
pop-mobilethe black and blue look you see in the the
STK themes comply with the principles of Responsive Web Design, but Magnolia can be configured to adapt to all design approaches. See thearticle for more information.
For more information on the
pop-mobile theme see the Mobile page.
Themes are configured in STK > Themes. The four configuration nodes define the individual elements of a theme:
cssFilesdefines links to style sheets that you can access in STK > Resources.
imagingdefines image variations for the various renditions of an image on the page.
BodyClassResolverclass that resolves the
bodyClassof the page. See for more information.
head element of the HTML code. The
htmlHeader area definition in the 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 .
STK resources are stored in the
resources workspace. Resources can be loaded from three sources: classpath, file system or
resources workspace. See Resources loading for more information.
Far future caching
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:
trueinstructs the browser to cache style sheets for one year.
linkdefines the path to the CSS file.
mediadefines the media query associated with the linked CSS file. See for more information.
conditionalCommentdefines the conditional comment attribute associated with the linked CSS file. Conditional comments are used to overcome the limitations of legacy browsers. The
iestylesconfiguration 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
only screen and (min-device-width: 481px)
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:
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 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 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
Small optimizes the layout for narrow screens using media query
Mobile optimizes the layout for handheld devices using media query
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
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.
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.
jsFiles content node configures three scripts:
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/themes/pop/js to see them. The files are organized in folders for better maintenance, exchangeability and flexibility.
scriptloader-plugin.js that is provided. Note that Freemarker's
#list directive collects content from the referenced scripts.
variation is an STK specific configuration that defines the size of the target image and tells the whether cropping is allowed. Variations are configured in a theme rather than under the
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
large. When the image is positioned to the left or to the right of the abstract, the CSS class is just
content defines a CSS selector that matches any page elements that have both classes
width property in the variation instructs the imaging engine to create a 458 pixels wide image. Default value for
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 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-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
The example configuration below applies
InvertFilter to the
promo image variation. This filter inverts the RGB channels of an image.
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
Variations are implemented as an configured in the Configuration app >
/modules/imaging/config/generators/stk. You can add your own 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 for more information.
Creating a module for a theme
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.
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.
Theme install task
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.gif, use the
InstallTextResourcesTask and set the
stripExtension parameter to
false. Create a custom version handler by subclassing
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
- Copy the
pop-mobiletheme configuration in STK > Themes
/pop-mobileand adapt it to your project.
- Use your
mobile.csswithin this configuration.
- Use the existing mobile
- Create a
init-mobile-behaviour.jsscript 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.
The resources available in STK > Resources can be accessed using Magnolia’s: