Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

EditionCE, Cloud
License
MLA, GPL
IssuesDEVDECT
Maven sitedevdect
Latest version

The Device Detection module helps manage the complexity of mobile environments. The module detects requests originating from mobile devices using Mobile Detect, a lightweight Java library for detecting mobile devices. Coupled with Magnolia's channels functionality, you can create channels that define the content and format served to a particular device class. There is no need to duplicate content. The same web content can be served to all devices in a format that is optimized for each device.

Installing

Maven is the easiest way to install the module. Add the following to your bundle. The parent POM of your webapp project should set the latest version of the module automatically. Should you need to use a specific module version, you can define it using the <version/> in the dependency.

<dependency>
  <groupId>info.magnolia.devdect</groupId>
  <artifactId>magnolia-module-device-detection</artifactId>
</dependency>

Configuration

The default configuration detects mobile devices, splitting them into two groups: smartphones and tablets. You don't need to change anything unless you want to detect other types of devices or other capabilities.

Device detection filter

DeviceDetectionFilter is registered in the Magnolia filter chain at Configuration > /server/filters/deviceDetection. The purpose of this filter is to intercept the incoming request and discover the capabilities of the device based on its User-Agent header.

Node nameValue

 
server


 
filters


 
context


 
contentType


 
deviceDetection


 
class

info.magnolia.module.devicedetection.filter.DeviceDetectionFilter

 
enabled

true

 
multipartRequest


All devices identify themselves in the User-Agent request header. Here is an example what the header looks like when an iPhone 3GS requests the Magnolia International corporate home page. The header basically says "I am an iPhone running iOS 4.0.2 and the Safari browser".

GET / HTTP/1.1
Host: www.magnolia-cms.com
Connection: close
User-Agent: Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_0_2 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A400 Safari/6531.22.7

Device capability configuration

The Mobile Detect API provides the capabilities of mobile devices. It knows the specifications of several devices, broken down into groups. The API is built into the Device Detection module so no calls to outside services are needed during detection. Mobile Detect is a clone of Mobile ESP. We use the clone rather than the original because the clone provides a Maven artifact so we do not need to include the API code.

The API is registered in the Configuration app in /modules/device-detection/config/capability.

Node nameValue

 
device-detection


 
config


 
capability


 
class

info.magnolia.module.devicedetection.mobiledetect.MobileDetectDeviceCapability

The device detection filter asks the API if the requesting device is a smartphone or a tablet device. Once the device capabilities are identified, the filter creates a DeviceInfo object in the request and sets the following basic properties:

  • isSmartphone is true if the device is a smartphone.
  • isTablet is true if the device is a tablet.

If you want to implement your own device detection mechanism, look at these Java classes for examples.

Class

Description

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") DeviceDetectionModule

Implements ModuleLifecycle and ensures the used DeviceCapability's initCapability method (costly) is only called only once

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") MobileDetectDeviceCapability

Implements 

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") DeviceCapability
interface and provides information about the capabilities of the device. Gets the DeviceInfo

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") DeviceInfo

Provides information about the device. All attributes are initially set to defined defaults

Device channel configuration

In order to serve content to the device in an appropriate format, a channel is resolved next. The

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") DeviceChannelResolver
is registered in the Configuration app /server/rendering/channelManagement/channels. This resolver resolves the channel to use based on the DeviceInfo object.

Node nameValue

 
server


 
filters


 
IPConfig


 
i18n


 
security


 
rendering


 
channelManagement


 
channels


 
device


 
resolver


 
class

info.magnolia.module.devicedetection.DeviceChannelResolver

 
class

info.magnolia.channel.ChannelManagerImpl

The channel is mapped to a variation. The variation consists of templates and a theme that optimizes the content for displaying on the device.