Mobile And Touch Support
ZK provides out-of-the-box detection and support of mobile, tablet and touch-enabled devices.
General information
When detecting these devices, ZK will automatically perform the following actions:
- Detect if the device is mobile, and of which category
- Wire dedicated touch event listeners
- Load and apply Tablet UI improvements
Mobile detection
ZK uses the UserAgent string provided by the web browser to identify the client device. If the user sets their mobile browser to "request desktop page", ZK will detect it as a desktop device accordingly, based on the UserAgent string.
The following JavaScript flags may be set to true, or to a version number on the zk JavaScript object depending on the information provided by the UserAgent string.
Multiple flags may be set at the same time, if a browser belongs to multiple categories.
| flag | detects |
|---|---|
| zk.opera | Opera browser |
| zk.ff | Firefox browser |
| zk.linux | Linux OS / browser |
| zk.webkit | Webkit engine based browser |
| zk.chrome | Chrome browser |
| zk.safari | Safari browser |
| zk.edge_legacy | Edge browser (legacy, before webkit reimplementation) |
| zk.edge | Edge browser (Webkit implementation) |
| zk.ios | iOS device (iPhone, iPad, iPod) |
| zk.mac | Mac OS device |
| zk.ipad | iPad device |
| zk.android | Android device |
| zk.mobile | Mobile device of any type, used for mobile-specific behaviors below |
Dedicated touch event listeners
If ZK detects that the client browser is a mobile device with zk.mobile set to true and has touch capabilities (has at least one touch-point support navigator.maxTouchPoints > 0), then the dedicated touch listeners will be added to the page.
This includes swipe motion support, as well as direct support for touchStart, touchEnd and touchMove events when interacting with ZK components. This is transparent for the user, and simply allows touch actions to map to equivalent mouse actions.
disabling touch event support
Since 9.6.0
You may want to disable touch event support, for example to force hybrid devices to use only mouse controls.
Touch event support can be disabled with the org.zkoss.zkmax.touch.disabled library property.
Set to true to disable dedicated touch event support.
<library-property>
<name>org.zkoss.zkmax.touch.disabled</name>
<value>true</value>
</library-property>
Tablet UI Improvements
If ZK detects that the client browser is a mobile device with zk.mobile set to true, then the Tablet UI Improvements will be added to the page.
Tablet UI Improvements are a series of modifications to out-of-the-box ZK component, which improves their usability on mobile devices. This includes replacing dropdowns by scrollers, replacing scrolls with swipes, etc.
For the full list of changes, please refer to Tablet UI improvements.
disabling Tablet UI Improvements
You may want to disable tablet UI improvements, for example to the page to use the same control on all clients, instead of using client-specific controls.
Tablet UI Improvements can be disabled with the org.zkoss.zkmax.tablet.ui.disabled library property.
Set to true to disable dedicated touch event support.
<library-property>
<name>org.zkoss.zkmax.tablet.ui.disabled</name>
<value>true</value>
</library-property>