Home » Shop Talk »

Insite Detection Helper: A WordPress Plugin

Insite Detection Helper

Available Soon

Insite Detection Helper adds class values to the body element and provides javascript variables, shortcode and PHP template tags to aid in coding for mobile devices.

Insite Detection Helper plugin for WordPress provides a straight-forward and intuitive alternative to using @media break points when writing CSS for mobile devices. It also provides Javascript variables and shortcode, plus PHP functions which you can use in theme development to design your website for phones, tablets and computers.

The plugin detects the visitor’s device type and provides tools to help code for it appropriately.

Optionally, the plugin provides tools to code for your visitor’s specific browser.

Insite Detection Helper reports that you are using:

Is this correct?

Please help us improve our plugin by filing a report to let us know!

Corrections

Your device:

Device brand:

Device model:

Your browser:

Browser version:


  (Orientation is not reported on computers.)

Completely Optional:

Message (if you'd like)

Your Name (would be helpful)

Your Email (also helpful)

On this page:

  1. Device Detection
  2. Browser Detection
  3. How It Works
  4. Usage Instructions

Device Detection Helpers

Insite Detection Helper provides these body classes:

  1. either: ‘phone’, ‘tablet’ or ‘computer’;
  2. either: ‘handheld’ or ‘not-handheld’ (‘handheld’ is equivalent to “phone OR tablet”);
  3. either: ‘portrait’ or ‘landscape’ (only if a mobile device is used.)

Device orientation class is updated on each change of orientation.

For example:

<body class="computer not-handheld your-themes-other-body-classes">

or:

<body class="phone handheld landscape your-themes-other-body-classes">

or perhaps:

<body class="tablet handheld portrait your-themes-other-body-classes">

These javascript variables and functions are provided in the head of the document:

  1. insiteHelper.device = ‘phone’, ‘tablet’ or ‘computer’;
  2. insiteHelper.handHeld = ‘yes’ or ‘no’;
  3. insiteHelper.mode.current = ‘portrait’ or ‘landscape’; (Only supplied if a handheld device is in use.)
  4. Available “hook-able” functions are:
    • insiteHelper.mode.onChange = function(){}; (Only supplied if a handheld device is in use.)
    • insiteHelper.mode.onPortrait = function(){}; (Only supplied if a handheld device is in use.)
    • insiteHelper.mode.onLandscape = function(){}; (Only supplied if a handheld device is in use.)

The insiteHelper.mode.current variable is updated on each change of orientation (as well as upon page load.) The “hook-able” functions are invoked whenever the device orientation changes, and you can make use of them in your own javascript (see “Usage” section for details.)

For example:

<head>
<!-- other head content would be here -->
<script type="text/javascript" id="insite-detection-helper-globals">
var insiteHelper = insiteHelper || {}; insiteHelper.mode = insiteHelper.mode || {}; // plugin namespace objects
insiteHelper.device = "phone";
insiteHelper.handHeld = "yes";
insiteHelper.mode.current = ""; // value is current device orientation, generated dynamically
// Plugin hook-able functions are:
insiteHelper.mode.onChange = function(){};
insiteHelper.mode.onPortrait = function(){};
insiteHelper.mode.onLandscape = function(){};
</script>

These shortcodes are made available:

[detection report="device"]
[detection report="handheld"]
[load only="$device"]$content[/load]
[load except="$device"]$content[/load]

Used in the WordPress post or page editor, the [detection] shortcode will output the user’s device type (computer, phone or tablet) or mobile status (“handheld” or “not handheld”.)

The [load][/load] shortcode will selectively load content on (or withhold it from) the devices specified.

These PHP theme tags (functions) are made available for use in theme files:

the_idh_report('device')
and
get_the_idh_report('device')

Optional: Browser Detection Helpers

If used in conjunction with the excellent WordPress plugin PHP Browser Detection (https://wordpress.org/plugins/php-browser-detection/), additional helpers are made available. Install and activate the PHP Browser Detection plugin for this additional functionality:

These additional body classes are added:

  1. browser (ex: firefox)
  2. browser-version (ex: firefox-37-0)

These additional Javascript variables are added to the head of the document:

  1. insiteHelper.browser = (ex: firefox)
  2. insiteHelper.browserVersion = (ex: 39.0)

These additional shortcodes can be used:

[detection report="browser"]
[detection report="version"]

These additional PHP tags are made available for use in theme files:

the_idh_report('browser')
the_idh_report('version')
get_the_idh_report('browser')
get_the_idh_report('version')

How It Works

Device detection is made possible by code provided by the wonderful MobileESP Project. The Insite Detection Helper plugin uses this excellent code to provide reliable device detection. We add additional javascript detection to determine the orientation of your visitor’s mobile device; a javascript listener updates when the visitor’s device orientation changes.

The plugin then provides you with tools (body classes, javascript variables, shortcodes and PHP template tags) to make coding for the visitor’s device simple and straight-forward.

Optionally, browser detection can be provided by the PHP Browser Detection plugin. Browser detection helpers (additional body classes, javascript variables, shortcodes and PHP theme tags) are provided only if you have the PHP Browser Detection plugin installed and enabled.

Note: MobileESP code is included in this plugin, which does the actual work of detecting the user’s device. This plugin does not provide browser detection. If you need browser detection, we recommend that you install and activate the PHP Browser Detection plugin. The Insite Detection Helper plugin checks if the PHP Browser Detection plugin is active; if it is, we provide tools that help you use some of the information that it provides.

Note: The Insite Detection Helper plugin does not automaically switch your theme, like some other device-theming plugins; it does not automatically change the appearance of your website. Rather, it provides you with tools which help you to do those things in whatever manner you prefer; it helps you write device-aware and browser-aware code. It is meant to help you design mobile-friendly websites!

Usage Instructions

CSS Usage

Body classes are automatically added to your HTML:

<body class="computer not-handheld your-themes-other-body-classes">

or:

<body class="tablet handheld portrait your-themes-other-body-classes">

or:

<body class="tablet handheld landscape your-themes-other-body-classes">

or:

<body class="phone handheld portrait your-themes-other-body-classes">

or:

<body class="phone handheld landscape your-themes-other-body-classes">

With optional browser detection, an example might be:

<body class="phone handheld landscape chrome chrome-43-0 your-themes-other-body-classes">

Rather than writing your CSS code using @media breakpoints, you can write simple, straight-forward and intuitive CSS code like this:

.computer  #your-div {
  /* styles for computer-only go here */
}
.handheld  #your-div {
  /* styles for both tablets and phones */
}
.tablet  #your-div {
  /* styles for tablets */
}
.tablet.portrait  #your-div {
  /* styles for tablets in portrait mode */
}
.tablet.landscape  #your-div {
  /* styles for tablets in landscape mode */
}
.phone  #your-div {
  /* styles for phones */
}
.phone.portrait  #your-div {
  /* styles for phones in portrait mode */
}
.phone.landscape  #your-div {
  /* styles for phones in landscape mode */
}

Alternately, you could use Insite Detection Helper’s PHP template tag functions to conditionally load separate device-specific stylesheets; see the PHP template tag usage example later on this page.

Javascript Usage

A script tag is automatically added to the head of your document. It provides variables and functions to assist in writing environment-aware javascript code, utilizing the detection results. With optional browser detection installed, it might look like this:

<head>
<!-- other head content would be here -->
<script type="text/javascript" id="insite-detection-helper-globals">
var insiteHelper = insiteHelper || {}; insiteHelper.mode = insiteHelper.mode || {}; // plugin namespace objects
insiteHelper.browser = "safari";
insiteHelper.browserVersion = "7.0";
insiteHelper.device = "phone";
insiteHelper.handHeld = "yes";
insiteHelper.mode.current = ""; // value is current device orientation, generated dynamically
// Plugin hook-able functions are:
insiteHelper.mode.onChange = function(){};
insiteHelper.mode.onPortrait = function(){};
insiteHelper.mode.onLandscape = function(){};
</script>

The namespace object’s variables and functions are available globally, so you can use them in your own javascript code.

You can use the variables in your own javascript like this:

// Always check first to make sure the plugin is active:
if (typeof insiteHelper.device !== 'undefined') {
	// Check for the conditions you need:
	if ((insiteHelper.device=='phone')) {
		alert('Hello, phone user!');
	}
};

Alternately you can use:

// Check for the conditions you need:
if ( jQuery('body').hasClass('phone') ) {
	alert('Hello, phone user!');
};
// Check for the conditions you need:
if ( jQuery('body').is('.phone.portrait') ) {
	alert('Turn your phone for a better view.');
}

The plugin contains a javascript listener to monitor the current orientation of your visitor’s handheld device. The insiteHelper.mode object utilizes this listener. You can hook into it easily from your own code.

The listener updates the value of the insiteHelper.mode.current variable each time your visitor turns his device.

The insiteHelper.mode functions are evoked (fired) each time your visitor’s handheld device orientation changes (as well as upon initial page load.) These functions are empty by default; no code is executed when they are evoked, unless you tell it what to execute. Because of their global availability, you can “hook into” these functions by defining them in your own javascript code.

In your own javascript file, you can define them like this:

// Hook into the Insite Detection Helper plugin's orientation functions.
// Be sure this is written OUTSIDE of any other functions.
// No need to define these functions unless the visitor has a handheld device...
if (jQuery('body').hasClass('handheld')) {
	// define what should happen each time an orientation change is detected...
	function insiteHelper.mode.onChange() {
		// events defined here will occur on EVERY orientation change
	};
	function insiteHelper.mode.onPortrait() {
		// events defined here will occur on every change INTO PORTRAIT MODE
	};
	function insiteHelper.mode.onLandscape() {
		// events defined here will occur on every change INTO LANDSCAPE MODE
	};
};

Any code that you define in these functions will be executed each time the device orientation changes. As a simple illustration, the following code will log all orientation changes to the console, and dynamically fill the empty <span class="orientation-report"> </span> elements in my HTML with the current orientation, updating the text on each change of orientation:

// Hook into the Insite Detection Helper plugin's orientation functions.
// Be sure this is written OUTSIDE of ANY other functions.
// No need to define these functions unless the visitor has a handheld device...
if (jQuery('body').hasClass('handheld')) {
	// define what should happen each time an orientation change is detected...
	function insiteHelper.mode.onChange() {
		// log all orientation changes to the console:
		console.log('Device orientation was changed.');
	};
	function insiteHelper.mode.onPortrait() {
		// log all changes into portrait mode to the console:
		console.log('Orientation mode is portrait.');
		// check for, and fill, all spans with class "orientation-report":
		if (jQuery('span.orientation-report').length) {
			jQuery('span.orientation-report').html('portrait');
		};
	};
	function insiteHelper.mode.onLandscape() {
		// log all changes into landscape mode to the console:
		console.log('Orientation mode is landscape.');
		// check for, and fill, all spans with class "orientation-report":
		if (jQuery('span.orientation-report').length) {
			jQuery('span.orientation-report').html('landscape');
		};
	};
};

A simplified version would use the insiteHelper.mode.current variable, like this:

// Hook into the Insite Detection Helper plugin's orientation functions.
// Be sure this is written OUTSIDE of ANY other functions.
// No need to define these functions unless the visitor has a handheld device...
if (jQuery('body').hasClass('handheld')) {
	// define what should happen each time an orientation change is detected...
	function insiteHelper.mode.onChange() {
		// log all orientation changes to the console:
		console.log('Device orientation was changed.');
		// check for, and fill, all spans with class "orientation-report":
		if (jQuery('span.orientation-report').length) {
			jQuery('span.orientation-report').html(insiteHelper.mode.current);
		};
	};
};

By defining the insiteHelper.mode functions in your own script, you can create any kind of events, and they will execute whenever your visitor turns their handheld device.

Shortcode Usage

These “detection” shortcodes can be used in the WordPress post/page editor:

[detection report='device']
[detection report='handheld']

Optionally (with PHP Browser Detection installed):

[detection report='browser']
[detection report='version']

For example, using these shortcodes in the WordPress editor:

You are using [detection report='browser'] (version [detection report='version']) on a [detection report='device']; your device is [detection report='handheld'].

will result in:

You are using Browser-detection (version not-installed) on a computer; your devide is not handheld.

You can also use the [load][/load] shortcode in the WordPress post/page editor to selectively serve content to the devices you choose. For example:

[load only='computer']Hello, computer user![/load][load except='computer']Hello, mobile user![/load] (Your device is [detection report='handheld'].)

will produce:
Hello, computer user! (Your device is not handheld.)

Use the only attribute to specify a device-type on which to load the content. Use the except attribute to specify a device-type on which to exclude the content. Allowable values are: ‘computer’, ‘tablet’, ‘phone’ and ‘handheld’ (‘handheld’ is shorthand for phone AND tablet; only=’handheld’ is equivalent to except=’computer’.)

PHP Template Tags Usage

You can use the following PHP template tags (functions) in your theme files:

the_idh_report('device');
get_the_idh_report('device');
/* and optionally... */
the_idh_report('browser');
get_the_idh_report('browser');
the_idh_report('version');
get_the_idh_report('version');

For example, in a theme template, the following will output an element for computer users only:

<?php 
// Always check if plugins are active before using them,
// otherwise your site will break if they are disabled...
if ( (function_exists('get_the_idh_report')) && (get_the_idh_report('device')=='computer') ) : ?>
<div class="computer-only">This element will only be output for computer users.</div>
<?php endif; ?>

This example will generate a device-specific message:

<?php 
// Always check if plugins are active before using them,
// otherwise your site will break if they are disabled...
if (function_exists('get_the_idh_report')) {
	$your_device = get_the_idh_report('device');
	$device_message = 'Welcome, '.$your_device.' user!';
} else { // fallback in case plugin is not installed
	$your_device = 'undefined'; 
	$device_message = 'Welcome!'; 
};
?>
<div class="<?php the_idh_report('device'); ?>-message"><?php echo $device_message; ?></div>

This example will load device-specific stylesheets (only) where appropriate; put this in your functions.php file:

function mytheme_device_stylesheet_manager() {
	global $wp_styles;
	
	// Register and enqueue stylesheets named tabletstyles.css and phonestyles.css from your childtheme's css directory.
	// For registering and enqueueing stylesheets, use these: $handle, $src, $deps, $ver, $media
	// For $src, use get_stylesheet_directory_uri() for files in a childtheme directory or get_template_directory_uri() for files in a parent theme directory.
	// For $deps, your theme's main stylesheet commonly has the theme's name registered as its handle; usually "themename", "themename-style", "themename_style", "themename-css" or similar.
	
	// Enqueue this stylesheet just for tablets:
	if ( (function_exists('get_the_idh_report')) && (get_the_idh_report('device')=='tablet') ) {
		wp_register_style(
			'tabletstyles', // handle name
			get_stylesheet_directory_uri() . '/css/tabletstyles.css', // the URL of the stylesheet; 
			array( 'your_theme_stylesheet_handle' ), // an array of handles of stylesheets that this stylesheet is dependant on;
			false, // version number optional, or false
			'screen' // CSS media type
		);
		wp_enqueue_style( 'tabletstyles' );
	};
	
	// Enqueue this stylesheet just for phones:
	if ( (function_exists('get_the_idh_report')) && (get_the_idh_report('device')=='phone') ) {
		wp_register_style(
			'phonestyles', 
			get_stylesheet_directory_uri() . '/css/phonestyles.css', 
			array( 'your_theme_stylesheet_handle' ), 
			false, 
			'screen'
		);
		wp_enqueue_style( 'phonestyles' );
	};
	
};
add_action( 'wp_enqueue_scripts', 'mytheme_device_stylesheet_manager' );

Note:

  • PHP template tags cannot detect device orientation, which is only determined client-side, using javascript.
  • the_idh_report($report) prints (displays) the requested information, in human-friendly form: browser name in title case, version as xx.x. Ex: Firefox 39.0
  • get_the_idh_report($report) returns the requested information, in machine-friendly form: browser name in lower case, version as xx-x. Ex: firefox 39-0

Use get_the_idh_report($report) to return the report value instead of outputting it directly.

Also on this page:

Post a Comment

Your email is never published nor shared. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*
*