The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.
Installing
<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 name | Value |
---|---|
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 name | Value |
---|---|
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
istrue
if the device is a smartphone.isTablet
istrue
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 |
$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
/server/rendering/channelManagement/channels
. This resolver resolves the channel to use based on the DeviceInfo
object.Node name | Value |
---|---|
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.