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 Templating Kit > 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.

Templating Kit > 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 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.

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.

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.

Stage

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.

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 Templating Kit > Site Definitions /default/variations/smartphone/theme/name.

The theme is configured in Templating Kit > 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.

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 Templating Kit > 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 Templating Kit > 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.

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 Templating Kit > Dialog Definitions > /generic/pages/tabChannels. Reference it from your component dialogs.

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 content 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 Templating Kit > Template Definitions. Exclude the entire area if you think it unnecessarily clutters the smartphone site.

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

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 Templating Kit > Dialog Defintions /components/teasers/stkTeaserCarousel add a new content node tabChannels.
  2. Add a data node extends and set the value to /modules/standard-templating-kit/dialogs/generic/pages/tabChannels. The extends mechanism tells Magnolia to use the referenced configuration.

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 content node tabChannels.
    • Add a data node extends and set the value to /modules/standard-templating-kit/dialogs/generic/pages/tabChannels.
    • Add another data node label and type in an appropriate value. This is the tab label.
  2. Add a new content node excludeChannels under the tabChannelsnode. This is the field node and the name matches the field in the generic dialog.
    • Add two data nodes description and label and 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.

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

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:

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

To comment, create an account and log in.

© Copyright 2023 Magnolia