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

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

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:

  • Channels a core Magnolia feature.
  • Device Detection module that identifies the requesting device, determines its capabilities and sets the DeviceInfo object in the aggreation state.
  • STK that includes the device channel and smartphone variation 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:

  • Page layout is rearranged to promote important content.
  • Image sizes are reduced.
  • Unnecessary CSS and JavaScript is excluded.

Watch a video about this feature.

Device channel

The device channel groups devices in three categories: smartphone, tablet and desktop. This channel is configured in STK > Channels /channels/device. The 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.

Node nameValue

 channels

 

 device

 

 resolver

 

 class

info.magnolia.module.devicedetection.DeviceChannelResolver

 class

info.magnolia.channel.ChannelManagerImpl

STK > Channels is a shortcut to Configuration > /server/rendering/channelManagement/channels

For more information see Device capability configuration and Mobile rendering process below.

Smartphone variation

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: ConfiguredRenderableDefinition . The 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 extending. It used all over Magnolia.

The example smartphone variation that ships with the STK reduces the page loading time with minimized CSS, JavaScript and images. The templates and the CSS change the layout to better match the device's screen orientation and resolution, removing page components that don't work well on a mobile or touch device.

Smartphone variations that apply globally to all sites are configured in STK > 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.

Node name

 variations

 smartphone

 templates

 theme

Multisite is an EE feature. In the CE, the variations node is at the top level.

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.

Templates

The smartphone variation uses all the STK elements except those configurated as variations.

Navigation

Site navigation is congifured in Templating Kit > Site Definitions /default/variations/smartphone/templates/prototype/navigation. The bottom and top properties allow you to change where navigation renders on the page. The default is top and by setting bottom to true and top to false this is reversed.

Node nameValue

 variations

 

 smartphone

 

 templates

 

 prototype

 

 navigation

 

 bottom

 true

 top

false 

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.

Areas

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.

Node nameValue

 variations

 

 smartphone

 

 templates

 

 prototype

 

 navigation

 

 areas

 

 promos

 

 enabled

 false

Stage

The stage components are designed for the desktop experience and are not suitable for smartphones. This component is diabled in STK > Template Definition /pages/stkHome/variations/smartphone/areas/stage/enabled. It cannot be disabled in the prototype because this would affect the default variation.

Node nameValue

 pages

 

 stkHome

 

 variations

 

 smartphone

 

 areas

 

 stage

 

 enabled

 false

With the exception above, all STK template and dialog definitions are used as is for the smartphone site.

Template script

The smartphone variation uses the same template script (main.ftl) as the default desktop version. You can access main.ftl at Templating Kit > Templates /templating-kit/pages.

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 top and bottom navigation parameters are used to render the navigation differently for the default site and smartphone variation.

<body ${bodyID} ${bodyClass}>
    <div id="wrapper">
        [@cms.area name="branding" content=content/]
        [#if def.navigation.top]
            [#include def.navigation.horizontal.template]
        [/#if]
        [@cms.area name="stage"/]
        [@cms.area name="sectionHeader" content=content/]
        <div id="wrapper-2">
        [#if def.navigation.top]
            [#include def.navigation.vertical.template]
        [/#if]
            <div id="wrapper-3">
                [@cms.area name="platform"/]
                [@cms.area name="main" content=content/]
                [@cms.area name="extras"/]
            </div><!-- end wrapper-3 -->
            [@cms.area name="promos"/]
            [@cms.area name="base"/]
        </div><!-- end wrapper-2 -->
        [#if def.navigation.bottom]
            [#include def.navigation.horizontal.template]
            [#include def.navigation.vertical.template]
        [/#if]
        [@cms.area name="footer"/]
    </div><!-- end wrapper -->
</body>

Here's a visual comparison of desktop and smartphone layouts on an STK article page. The red square is an approximate browser viewport.

Theme

The smartphone-specific pop-mobile theme is referenced in the default site definition in STK > Site Definitions /default/variations/smartphone/theme/name.

Node nameValue

 variations

 

 smartphone

 

 theme

 

 name

 pop-mobile

The theme is configured in STK > Themes /pop-mobile. Like all themes it defines the site look and feel with CSS and provides client-side functionality through JavaScript. Compared to the standard pop theme, the pop-mobile theme is lighter. It uses a single CSS file and fewer JavaScripts.

The theme definition defines:

  1. A cascading style sheet mobile.css.
  2. JavaScript aggregators that load only mobile-specific libraries and plugins.
  3. Imaging variations that create smaller proxy images.
Node nameValue

 pop-mobile

 

 cssFiles

 

 mobile

 

 farFutureCaching

 true

 link

 /resources/templating-kit/themes/pop/css/mobile.css

 media

 screen

 jsFiles

 

 init-libraries

 

 farFutureCaching

 true

 link

/resources/templating-kit/js/mobile-scriptloader-libraries.js

 init-plugin

 

 init-theme

 

 imaging

 

 variations

 

 content

 

 content-small

 

For more information about themes see:

CSS

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:

[#assign pageModel = model.root!]
[#assign pageDef = pageModel.definition!]
....
[#list pageDef.cssFiles as cssFile]
   <link rel="stylesheet" type="text/css" href="${cssFile.link}" media="${cssFile.media}" />
[/#list]

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.

    @media only screen and (min-width : 470px) { /* Landscape */
    .teaser-wrapper .rack-teaser {
        width: 470px;
    }
    
  • Smartphone-specific navigation arrows.

    background: url(../img/icons/mobile-sprites.png) 0 5px no-repeat;

Nearly all icons and background images are shared by both themes. The few smartphone-specific images such as navigation arrows are in STK > Resources /templating-kit/themes/pop/img. You will recognize them by their file names.

JavaScript

The pop-mobile theme includes a minimized version of the standard JavaScript library, tailored for the smartphone experience. The aggregator scripts load only libraries that make sense on mobile devices. They exclude libraries that only desktop users would benefit from such as jQuery libraries for mouse wheel support and date pickers. Mobile devices typically provide proprietary mechanisms for these actions.

JavaScript references are included in the HTML document header using the same mechanism as style sheets. As long as your theme defines the JavaScript reference correctly, they are included in the header automatically. Here's the relevant extract from the htmlHeader script:

[#assign pageModel = model.root!]
....
[#list stkfn.theme(pageModel.site).jsFiles as jsFile]
    <script src="${jsFile.link}" type="text/javascript"></script>
[/#list]

You can find the aggregator scripts in STK > Resources:

  • templating-kit/js:
    • mobile-scriptloader-libraries.js loads core jQuery functions needed on mobile devices.
    • mobile-scriptloader-plugin.js loads jQuery plugins for specific tasks needed on mobile devices.
  • templating-kit/themese/pop/js:
    • init-mobile-behaviour.js initializes teaser switching, embedded video player, animations in the FAQ paragraph, and other client-side functionality specific to the pop-mobile theme.

Imaging

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.

Node nameValue

 pop-mobile

 

 imaging

 

 variations

 

 stage

 

 rule

 

 cssSelector

 #stage

 height

 143

 width

 420

Targeting specific content

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:

  • If you have a survey page or component and the questions are about the desktop experience, exclude it from the smartphone sites.
  • Deliver a different stage component to mobile users, while the rest of the page is common to all visitors.

The generic tab definition is in STK > Dialog Definitions > /generic/pages/tabChannels. Reference it from your component dialogs.

Node nameValue

 generic

 

 pages

 

 tabChannels

 

 fields

 

 label

 dialogs.generic.pages.tabChannels.label

The ChannelVisibilityContentDecorator 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 node. If no such property is found at the time of rendering, the content is available in all channels.

Previewing mobile content

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 smartphone variation.

.

The Tablet preview uses the standard pop theme and the default variation. This is the same experience a desktop user gets.

.

Mobile rendering process

Here is a technical overview of what happens when a mobile device requests a page.

  1. A mobile device requests a page and identifies itself in the User-Agent header.
  2. DeviceDetectionFilter reads the user agent string and passes it to the Device Detection module.
  3. Device Detection module queries a Mobile ESP database for the device's capabilities and stores them in a DeviceInfo object. In the case of a smartphone, the object now contains the fact that it is a smartphone and its screen width and height.
  4. MultiChannelFilter resolves a channel to use based on the device info. It sets the channel name in the aggregation state.
  5. ChannelVariationResolver finds a matching smartphone variation.
  6. SiteMergeFilter merges the site definition with the variation.
  7. ChannelVisibilityContentDecorator hides content based on the multivalue property excludeChannels.
  8. RenderingFilter renders the merged content.

Modifying the smartphone 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:

Exclude an area

We use the base area in the prototype as an example. The stkTeaserCarousel and 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 STK > Template Definitions. Exclude the entire area if you think it unnecessarily clutters the smartphone site.

To exclude base area for all templates in STK > Site Definitions /default/variations/smartphone/templates/prototype/areas copy the /promos node and rename it base.

Node nameValue

 variations

 

 smartphone

 

 templates

 

 prototype

 

 areas

 

 promos

 

 base

 

 enabled

false 

Allow editors to exclude components

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 stkTeaserCarousel dialog:

  1. In STK > Dialog Defintions/components/teasers/stkTeaserCarousel add a new node tabChannels.
  2. Add an extends property and set the value to /modules/standard-templating-kit/dialogs/generic/pages/tabChannels. The extends mechanism tells Magnolia to use the referenced configuration.
Node nameValue

 components

 

 teasers

 

 stkTeaserCarousel

 

 form

 

 tabs

 

 tabTeaser

 

 tabChannels

 

 extends

/modules/standard-templating-kit/dialogs/generic/pages/tabChannels 

The 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 label and 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 i18nBasename properties.

To add the generic tabChannels tab to to the catCloud dialog:

  1. In Configuration >/modules/categorization/dialogs/catCloud add a new node tabChannels.
    • Add an extends property and set the value to /modules/standard-templating-kit/dialogs/generic/pages/tabChannels.
    • Add another property label and type in an appropriate value. This is the tab label.
  2. Add a new node excludeChannels under the tabChannelsnode. This is the field node and the name matches the field in the generic dialog.
    • Add two properties description and label and type in appropriate values.
Node nameValue

 modules

 

 categorization

 

 dialogs

 

 catCloud

 

 form

 

 tabs

 

 tabMain

 

 tabChannels

 

 fields

 

 excludeChannels

 

 description

Choose the channels where this content should NOT be served

 label

Check to exclude

 extends

/modules/standard-templating-kit/dialogs/generic/pages/tabChannels 

 label

Output Channels 

Editors can now exclude either component from any site. Here's the cloud on the smartphone site with the carousel excluded.

Change navigation at template level

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 STK > 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 smartphone variation:

  • The /navigation/horizontal/enabled node disables the horizontal navigation.
  • The /navigation/vertical/levels node sets vertical navigation to 3 levels.
  • The /navigation/bottom and /top properties reverse the settings in the global smartphone configuration.
  • The /smartphone/class property set to STKPage ensures that the correct class is instantiated during the template merging process.
Node nameValue

 pages

 

 stkArticle

 

 variations

 

 smartphone

 

 navigation

 

 horizontal

 

 enabled

false 

 vertical

 

 level

 bottom

false

 top

true

 class

info.magnolia.module.templatingkit.templates.pages.STKPage

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 ConfiguredTemplateDefinition that does not have a navigation variable.

Here's the 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.

Configuring a tablet variation

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:

  • The pop-mobile theme is used.
  • The the stage component still renders on the Home page.
  • Promos are disabled.

Letting the user select the variation

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 MultiChannelFilter goes through all the channels in order to resolve them.

Test these examples on the demopublic site:

  • No labels