Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
The Standard Templating Kit (STK) allows you to configure variations of the default site for different mobile devices. The same content is used for mobile devices and desktop browsers. There is no need to create device-specific versions of pages, as the content is formatted and optimized to match the device's capabilities.
A large number of users consume Web content using mobile devices rather than a full desktop browser. These smaller devices may not be capable of rendering all types of content or the desktop layout of a Web page may not work well on a small screen. A channel aimed at smartphone users formats the content differently. It leaves out areas that do not work well on a small screen and only includes functionality that benefits smartphone users.
Magnolia's approach complies with the principles of Responsive Web design, an approach that creates websites that adapt to the visitor. The approach relies on three technical ingredients: fluid grids, flexible images and media queries.
The mobile functionality uses three features to serve appropriate content to a device:
DeviceInfoobject in the aggreation state.
smartphonevariation configurations. Variations define how content should be transformed for a given channel.
As long as your pages use STK templates, your site is automatically smartphone-optimized and the:
Watch a video about this feature.
device channel groups devices in three categories:
desktop. This channel is configured in Templating Kit > Channels
class node registers the
DeviceChannelResolver that checks the
DeviceInfo object to see if the request is made by a smartphone and returns the
smartphone attribute. A matching
smartphone variation is preconfigured in the STK. This variation outputs content suitable for a smartphone.
Templating Kit > Channels is a shortcut to Configuration >
A variation defines what the smartphone site looks like by controlling what areas and components are used. The principle is that the same content is used for all variations. There is no need to create device-specific pages unless you want to.
Typically a variation modifies the template prototype and registers an appropriately optimized theme. If you compare the
smartphone variation to the
default site definition you can see that they are very similar. Both have a
templates and a
theme node. This is because they are actually two instances of the same object:
smartphone variation extends the
default site definition in the same way that the individual site definitions, like
demo-project, do. You can extend the default configurations that work well on a smartphone and define exceptions for configurations that don't. This mechanism is known as . It used all over Magnolia.
Smartphone variations that apply globally to all sites are configured in Templating Kit > Site Definitions
/default/variations. Variations can also be defined on a site level i.e. in
/<site name>/variations, or on an individual template level i.e in Template Definitions. You can find the
smartphone variation under the
default site definition.
Multiple sites is an EE feature. In the CE the
variations node is a top level node configured in Templating Kit > Site Configuration.
The exceptions that the
smartphone variation defines are dealt with in the sections that follow.
For SEO reasons it is important that your desktop and smartphone sites use the same URL. Defining the smartphone variation under the
default site definition ensures that it applies to all URLs.
smartphone variation uses all the STK elements except those configurated as
Site navigation is congifured in Templating Kit > Site Definitions
top properties allow you to change where navigation renders on the page. The default is
top and by setting
false this is reversed.
Both the horizontal and vertical navigation are rendered below the extras area at the bottom of the page just above the footer. This improves the user experience on the small screen by placing the main content higher. On an article page, the main content is now visible in the first screenful without scrolling.
The promos area is unsuitable for the dimensions of a smartphone screen. By default it would render below
extras making the page on the small screen very long. This area is enabled for all templates in the prototype. Setting the
/default/variations/smartphone/templates/prototype/areas/promos/enabled node to
false disables the area for smartphones.
The stage components are designed for the desktop experience and are not suitable for smartphones. This component is diabled in Templating Kit > Template Definition
/pages/stkHome/variations/smartphone/areas/stage/enabled. It cannot be disabled in the prototype because this would affect the default variation.
With the above exception all STK template and dialog definitions are used as is for the smartphone site.
smartphone variation uses the same template script (
main.ftl) as the default desktop version. You can access
main.ftl at Templating Kit > Templates
The script uses
div elements as wrappers. Divs are generic block-level containers that are easy to style with CSS. While CSS gives you lots of flexibility regarding positioning, the elements must still be rendered in their order of importance in the HTML.
Here's the script. Note how the
bottom navigation parameters are used to render the navigation differently for the
default site and
Here's a visual comparison of desktop and smartphone layouts on an STK article page. The red square is an approximate browser viewport.
pop-mobile theme is referenced in the
default site definition in Templating Kit > Site Definitions
The theme is configured in Templating Kit > Themes
pop theme, the
The theme definition defines:
For more information about themes see:
Cascading style sheets (CSS) are referenced in the header element of an HTML document. Magnolia substitutes the
mobile.css sheet for the desktop sheets automatically as long as the theme is defined correctly. The rendering of theme specific CSS takes place in the
htmlHeader script accessible in Templating Kit > Templates
/templating-kit/pages/global. Here's the relevant extract:
The single smartphone CSS file,
mobile.css, is accessible in Templating Kit > Resources
/templating-kit/themes/pop/css. It contains only rules applicable to smartphone sites. The file is light-weight, about 20% of the size of
styles.css used on the default desktop site. For demonstration purposes the smartphone site has a different color scheme. The color scheme is defined entirely in
mobile.css. This means that if you want to implement a completely different color scheme for your own smartphone site, you only need to edit CSS rules in this one file.
Here are some smartphone-specific style rule examples:
Set a minimum width for teasers in landscape mode, taking advantage of the increased screen real estate when the device is turned.
Smartphone-specific navigation arrows.
Nearly all icons and background images are shared by both themes. The few smartphone-specific images such as navigation arrows are in Templating Kit > Resources
/templating-kit/themes/pop/img. You will recognize them by their file names.
You can find the aggregator scripts in Templating Kit > Resources:
mobile-scriptloader-libraries.jsloads core jQuery functions needed on mobile devices.
mobile-scriptloader-plugin.jsloads jQuery plugins for specific tasks needed on mobile devices.
init-mobile-behaviour.jsinitializes teaser switching, embedded video player, animations in the FAQ paragraph, and other client-side functionality specific to the
Large images do not work well on smartphones. The CSS scales the images to display correctly but there is no benefit in serving images larger than the device's viewport. It is a waste of bandwidth. In
/pop-mobile/variations you can define imaging variations that create smaller proxy copies.
The STK provides a generic Output Channels tab that is available in all the page properties dialogs. You can also add the tab to individual component dialogs. The selected options will be excluded in the rendering process.
By default, content is delivered to all variations. To exclude a page or component from a variation, check the appropriate boxes. You can select more than one.
The ability to mark content for a variation at the page and component level is additional to and independent of the modifications defined in the variation. It opens up many possibilities, for example:
The generic tab definition is in Templating Kit > Dialog Definitions >
/generic/pages/tabChannels. Reference it from your component dialogs.
Java class provides this functionality. The tab reads the available variations attribute from
site.channels. It stores the selected variation in the multivalue
excludeChannels property under the content node. If no such property is found at the time of rendering, the content is available in all channels.
The preview function allows you to see the different channel variations on the devices they are intended for.
The channel names you see in the dropdown are hardcoded. For the moment they are not configurable.
The Smartphone preview uses the
pop-mobile theme and the
The Tablet preview uses the standard
pop theme and the default variation. This is the same experience a desktop user gets.
Here is a technical overview of what happens when a mobile device requests a page.
DeviceDetectionFilterreads the user agent string and passes it to the Device Detection module.
DeviceInfoobject. In the case of a smartphone, the object now contains the fact that it is a smartphone and its screen width and height.
SiteMergeFiltermerges the site definition with the variation.
You can modify the
smartphone variation to suit your needs by adapting the example variation configurations provided in the preceding sections.
To demonstrate how flexible variations are, we provide three further example configurations:
We use the
base area in the prototype as an example. The
catCloudWide components are available in this area in the prototype. The content of the carousel does not read well on a smartphone, but the category cloud adapts nicely to the small screen. You have two configurable options to ensure that your smartphone content renders perfectly.
Your first option is to exclude the
base area on all templates in the prototype. You can also exclude it for individual templates in Templating Kit > Template Definitions. Exclude the entire area if you think it unnecessarily clutters the smartphone site.
base area for all templates in Templating Kit > Site Definitions
/default/variations/smartphone/templates/prototype/areas copy the
/promos node and rename it
As an alternative to excluding the
base area, you can allow editors to determine whether an individual component should be excluded by adding the generic Output Channels tab to the component dialogs. We add the tab for both available components. This makes it possible to render the components on any, all, or none of the site variations.
To add the generic
tabChannels tab to to the
/components/teasers/stkTeaserCarouseladd a new content node
extendsand set the value to
extendsmechanism tells Magnolia to use the referenced configuration.
catCloudWide component is in the Categorization module and is edited by the
catCloud dialog. You can also use the
extends mechanism here but you need to manually replace the
description message bundle keys because you are extending a configuration from a different module, i.e. the original configurations reference different message bundles in the
To add the generic
tabChannels tab to to the
/modules/categorization/dialogs/catCloudadd a new content node
extendsand set the value to
labeland type in an appropriate value. This is the tab label.
tabChannelsnode. This is the field node and the name matches the field in the generic dialog.
labeland type in appropriate values.
Editors can now exclude either component from any site. Here's the cloud on the smartphone site with the carousel excluded.
In the template prototype both vertical and horizontal navigations are enabled and render at the top of the page. The global
smartphone variation configured in Site Definitions >
/default/variations/smartphone/templates/prototype/navigation retains both navigations but renders them above the footer. You can change this behaviour on a template level. The example configuration below reverts partially to the "desktop" behavior only for pages based on the
stkArticle template that are rendered by the
/navigation/horizontal/enablednode disables the horizontal navigation.
/navigation/vertical/levelsnode sets vertical navigation to
/topproperties reverse the settings in the global
/smartphone/classproperty set to
STKPageensures that the correct class is instantiated during the template merging process.
During the template merging process, definitions (including their
classes) in the prototype and concrete definitions are instantiated at the same time. If no
class property is found in the template definition, a fallback class is used. In the above example the fallback class is
that does not have a
demo-project/about/articles/standard-article page in preview mode on a smartphone. Only a three-level vertical navigation menu renders between the section and page headers.
Tablets use the default site variation because it works well on these devices. You can set up a
tablet variation in the same way as the smartphone variation if you like.Here is the result of simply copying and renaming the
smartphone variation to
tablet with no further modifications. Note the following:
pop-mobiletheme is used.
You can use the URL parameter
mgnlChannel to allow the user to select the channel. This can be used for example to provide links for navigation from a desktop variation to a smartphone variation and vice versa. This option is commonly provided by a link such as "View desktop version". When the user clicks the link, Magnolia serves the site using the default site definition. If the parameter is present in the URL, it is available in the context, and the system returns its value as the channel. If the parameter is not present, the
goes through all the channels in order to resolve them.
Test these examples on the