Handheld_XH - a CMSimple_XH Plugin

iPhone

Handheld_XH facilitates automatic detection of mobile browsers (not tablet browsers), so you can present them a mobile friendly website by either redirecting them to another site or by simply switching to a special template. The plugin can also be used by other CMSimple_XH components, which want to adapt to mobile browsers.

Please do read this documentation before you encounter any problems!

Requirements

Handheld_XH is a plugin for CMSimple_XH. It requires a UTF-8 encoded version.

back to top

Installation

The installation is done as with many other CMSimple_XH plugins. See the CMSimple_XH wiki for further details.

  1. Backup the data on your server.
  2. Unzip the distribution on your computer.
  3. Upload the whole directory handheld/ to your server into CMSimple_XH's plugins directory.
  4. Set write permissions to the subdirectories config/, css/ and languages/.
  5. Switch to "Handheld" in the back-end to check if all requirements are fulfilled.
back to top

Settings

The plugin's configuration is done as with many other CMSimple_XH plugins in the website's back-end. Select "Handheld" from "Plugins".

You have to change the default settings of Handheld_XH under "Config". Hints for the options will be displayed when hovering over the help icon with your mouse. See section Usage for details.

Localization is done under "Language". You can translate the character strings to your own language (if there is no appropriate language file available), or customize them according to your needs.

The look of Handheld_XH can be customized under "Stylesheet".

back to top

Usage

Handheld_XH has three modes:

  1. Redirect mobile browsers to another (sub)domain

    The preferred way to present a really mobile optimized website. The (sub)domain can be a minimal CMSimple_XH installation or even a small handcrafted website.

  2. Redirect mobile browsers to a CMSimple subsite

    A compromise solution: this way you can present a different content in a different template, but plugins that are not used on the mobile site might increase the network traffic.

    In CMSimple_XH 1.6 the dubious subsite feature has been removed, so this mode is obsolete.

  3. Use another template for mobile browsers

    Probably not the friendliest solution for mobiles, but this way you only have to keep one content up to date. Consider to use a responsive template instead.

Set the desired mode in the plugin's configuration, fill in the appropriate setting and create the mobile site resp. the template. It's good practise to present your mobile visitors a link to the full site:

<a href="http://www.example.com/?&amp;handheld_full=1">view full site (requires cookies enabled)<a>

"handheld_full=1" will set a cookie in the visitors browser, so he can navigate on the full site without being redirected to the mobile one. On the full site you'll want to set a link back to the mobile version:

<a href="http://mobile.example.com/?&amp;handheld_full=0">view mobile site<a>

After everything is set up, you are strongly encouraged to test it. If you don't have a smartphone, there are several possibilites, e.g. the Opera Mini Simulator, the Firefox Addon User Agent Switcher and the Opera Mobile Classic Emulator. Finally you can check your site with the W3C mobileOK Checker.

back to top

API

Other CMSimple_XH components (plugins/templates/addons) can use the browser detection of Handheld_XH to adapt for mobile browsers:

include_once $pth['folder']['plugins'] . 'handheld/handheld.inc.php';
if (Handheld_detected()) {
    // take appropriate actions
}
back to top

Limitations

The mobile browser detection relies on the user agent string that is sent by the browser. This information is not absolutely reliable as it might have been changed by the vendor or the owner of the mobile device.

In CMSimple_XH before 1.6 in mode 3 the mobile template might not work on pages where a page specific template is defined. This cannot be solved appropriately, so an upgrade to CMSimple_XH 1.6 is recommended.

back to top

License

Handheld_XH is licensed under GPLv3.

© 2011 Brett Allen
© 2012-2014 Christoph M. Becker

Slovak translation © 2012 Dr. Martin Sereday
Russian translation © 2012 Lubomyr Kydray
Czech translation and CTIMNE © 2012 Josef Němec

back to top

Credits

Handheld_XH is powered by Detect Mobile Browsers. Many thanks to Mktg Dept for publishing the mobile detection regex under the Unlicense.

The plugin icon is designed by pierocksmysocks. Many thanks for publishing this icon as freeware.

This plugin uses free applications icons from Aha-Soft. Many thanks for making these icons freely available.

Many thanks to the community at the CMSimple_XH forum for tips, suggestions and testing.

And last but not least many thanks to Peter Harteg, the "father" of CMSimple, and all developers of CMSimple_XH without whom this amazing CMS wouldn't exist.

back to top