Mobile And Touch Support

{{ZKDevelopersReferencePageHeader}}

__TOC__

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 [[ZK Component Reference/Tablet Devices|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 <code>zk</code> 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.

{| class="wikitable"
|+ Browser detection flags
|-
! 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 <code>zk.mobile</code> set to true and has touch capabilities (has at least one touch-point support <code>navigator.maxTouchPoints > 0</code>), 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 ===
{{versionSince| 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 [[ZK Configuration Reference/zk.xml/The Library Properties/org.zkoss.zkmax.touch.disabled|org.zkoss.zkmax.touch.disabled library property]].

Set to true to disable dedicated touch event support.
<source lang='xml'>
<library-property>
	<name>org.zkoss.zkmax.touch.disabled</name>
	<value>true</value>
</library-property>
</source>

== Tablet UI Improvements ==

If ZK detects that the client browser is a mobile device with <code>zk.mobile</code> 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 [[ZK Component Reference/Tablet Devices|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 [[ZK Configuration Reference/zk.xml/The Library Properties/org.zkoss.zkmax.tablet.ui.disabled|org.zkoss.zkmax.tablet.ui.disabled library property]].

Set to true to disable dedicated touch event support.
<source lang='xml'>
<library-property>
	<name>org.zkoss.zkmax.tablet.ui.disabled</name>
	<value>true</value>
</library-property>
</source>