adi_mobile – Mobile browser detection

This plugin implements the mobile browser detection capabilities of php-mobile-detect (by Victor Stanciu), together with some website mode switch functionality and viewport measurement.

Some new tags are included:

  • <txp:adi_mobile /> to perform the mobile browser detection & website mode function
  • <txp:adi_if_mobile /> to control content delivery
  • <txp:adi_mobile_script /> to add some jQuery to the page
  • <txp:adi_mobile_viewport /> to cope with subtle viewport width changes

Which Mobile?

adi_mobile will detect the following types:

  • Mobile – any mobile
  • Tablet – any tablet
  • Android
  • AndroidTablet
  • Blackberry
  • BlackberryTablet
  • Opera – Mini & Mobile
  • Palm
  • Windows
  • WindowsPhone
  • iPhone – or iPod
  • iPad
  • Generic – any mobile that doesn’t fall into the above camps

The above types can be used in the type and include attributes.

Note that tablets (e.g. iPad) are detected but are not advertised as a mobiles. This behaviour can be changed using the include attribute – see the Tablet examples below.

Installation & Requirements

Install the plugin in the usual way.

The <txp:adi_mobile /> tag must be placed at the top of your pages.

Use <txp:adi_if_mobile /> wherever required.

If you want to use the viewport detection mechanism then place the <txp:adi_mobile_script /> tag somewhere in the <head> and make sure you’ve got jQuery fired up as well.

Cookies are used to store the mobile “mode” and the viewport information. Note that if cookies are disabled then:

  • it will not be possible to disable the mobile detection functionality
  • the viewport detection mechanism will refresh every page

If javascript is disabled then adi_mobile won’t be able to measure the viewport.

Mobile Detection Mode

adi_mobile provides a mechanism whereby a user can select the “mode” of a website. By default, if a mobile browser is detected then adi_if_mobile reports it as such.

Some mobile users may prefer to see the website in all its desktop glory instead. This can be achieved by setting URL variable “mobile_mode”, for example:

www.mywebsite.com/?mobile_mode=disabled

The <txp:adi_mobile /> tag will pick this up and set a cookie. Further visits to the website by the user will be flagged as not being from a mobile. To re-enable mobile mode detection, use:

www.mywebsite.com/?mobile_mode=not_disabled

- the cookie will be cleared and mobile business resumed.

The Examples show a way of implementing this using adi_link.

If you’re using the viewport measurement mechanism then it’s advisable to force a reset at the same time:

www.mywebsite.com/?mobile_mode=not_disabled&viewport_reset

Viewport information

If required, adi_mobile will automatically attempt to measure the user’s viewport dimensions (width & height in pixels) plus orientation (in degrees). It does this by running a little bit of jQuery (see <txp:adi_mobile_script />), refreshing the page & recording the information in a cookie.

Ranges of widths can be defined and tested by adi_if_mobile. The defaults are “narrow” (320 or less) and “wide” (800+). These defaults may be modified using attributes in the adi_mobile tag.

Common mobile screen physical widths are:

  • Basic mobile – 320px
  • Android – 800px
  • Opera mobile – 850px
  • iPhone – 980px
  • Windows Phone 7 – 1024px

But these are often advertised as 320px when meta tags are used, e.g.

<meta name="viewport" content="width=device-width" />

The width, height and orientation are also stored in TXP variables: “adi_mobile_width”, “adi_mobile_height” & “adi_mobile_orientation”.

Once the viewport dimensions have been stored in a cookie, they will not be measured again. You can force a re-measurement, by setting URL variable “viewport_reset”, for example:

www.mywebsite.com/?viewport_reset

The Examples show a way of implementing this using adi_link as well as ways of delivering different content depending on viewport width or orientation.

Beware – sometimes the viewport dimensions can change without adi_mobile detecting it. Consider the following code:

<txp:adi_if_mobile orientation="v">
	<meta name="viewport" content="width=device-width" />
	<txp:adi_mobile_viewport width="320" />
<txp:else />
	<meta name="viewport" content="width=480" />
	<txp:adi_mobile_viewport width="480" />
</txp:adi_if_mobile>

Here, the viewport width is being changed by the <meta> tag during the page load, so the adi_mobile_viewport tag has to be used to override what was detected before the page loaded. The new width is then picked up by adi_if_mobile as normal.

Conditions of Use

The adi_if_mobile conditional tag works in a number of ways:

<txp:adi_if_mobile>
	- mobile browser detected (& mobile detection has not been disabled)
<txp:else />
	- no mobile detected (or mobile detection has not been disabled)
</txp:adi_if_mobile>
<txp:adi_if_mobile disabled="1">
	- mobile detection has been disabled
<txp:else />
	- mobile detection not disabled
</txp:adi_if_mobile>

You can deliver content according to the viewport width:

<txp:adi_if_mobile width="?">
	- viewport width unknown
<txp:else />
	<txp:adi_if_mobile width="narrow">
		- viewport is narrow
	<txp:else />
		<txp:adi_if_mobile width="wide">
			- viewport is wide
		<txp:else />
			- viewport is medium
		</txp:adi_if_mobile>
	</txp:adi_if_mobile>
</txp:adi_if_mobile>

Or to target a specific width:

<txp:adi_if_mobile width="885">
	- the viewport is exactly 885px wide
</txp:adi_if_mobile>

To check the orientation:

<txp:adi_if_mobile orientation="v">
	- the mobile is being held vertically (portrait mode)
</txp:adi_if_mobile>

You can negate the adi_if_mobile condition easily:

  • <txp:adi_if_mobile not="1">
  • <txp:adi_if_not_mobile>

Use whichever you’re comfortable with – they’re functionally equivalent.

A note on mobile context: When testing viewport & orientation adi_if_mobile will not return any output, regardless if the condition is true or false, if no mobile has been detected or if mobile mode has been disabled. For example:

<txp:adi_if_mobile width="narrow">
	- the viewport is narrow
</txp:adi_if_mobile>

is functionally equivalent to:

<txp:adi_if_mobile>
	<txp:adi_if_mobile width="narrow">
		- the viewport is narrow
	</txp:adi_if_mobile>
</txp:adi_if_mobile>

Known Unknowns

If the viewport width or orientation can’t be determined, then adi_mobile will invent some defaults:

  • Default width = narrow
  • Default orientation = vertical

The assumption being that if the mobile can’t run javascript then it must be a basic one or if it won’t run javascript then we have to use something.

Styling

Styling for mobiles is best served up using CSS media queries and media types (e.g. media="handheld"), but adi_mobile does provide additional options if required.

Deliver a specific stylesheet to a mobile browser:

<txp:adi_if_mobile>
	<link rel="stylesheet" type="text/css" href="mobile.css" media="handheld" />
</txp:adi_if_mobile>

There’s a TXP variable, automatically set by adi_mobile, which can be used to embed classes, e.g.

<txp:if_variable name="adi_mobile_types" value="">
	<body>
<txp:else />
	<body class="<txp:variable name="adi_mobile_types" />">
</txp:if_variable>

The variable contains the list of types detected by adi_mobile (see above, all lowercase).

Examples

Serve up specific code to any mobile:

<txp:adi_if_mobile>
	<meta name="viewport" content="width=device-width" />
</txp:adi_if_mobile>

Serve up specific code to an iPhone:

<txp:adi_if_mobile type="iphone">
	<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
</txp:adi_if_mobile>

Serve up specific code to an iPhone OR an Android:

<txp:adi_if_mobile type="iphone,android">
	<meta name="viewport" content="width=device-width" />
</txp:adi_if_mobile>

Prevent content from being presented to mobiles:

<txp:adi_if_not_mobile>
	... stuff to be show to non-mobiles only ...
</txp:adi_if_not_mobile>

To change the lower limit of a “wide” viewport to 980px:

<txp:adi_mobile wide="980" />

Links to switch between “Normal” and “Mobile” mode:

<txp:adi_if_mobile>
	Change to: <txp:adi_link section="" urlvars="mobile_mode=disabled" link_text="Normal view" />
</txp:adi_if_mobile>
<txp:adi_if_mobile disabled="1">
	Change to: <txp:adi_link section="" urlvars="mobile_mode=not_disabled&viewport_reset" link_text="Mobile view" />
</txp:adi_if_mobile>

Tablet examples

As mentioned earlier, the default behaviour is to detect tablets but not to flag them as mobiles. For example:

<txp:adi_mobile />
<txp:adi_if_mobile>
	MOBILES ONLY
<txp:else />
	DESKTOP & TABLETS
</txp:adi_if_mobile>

If you want tablets to be bundled with mobiles (e.g. in order to detect orientation) then use:

<txp:adi_mobile include="tablet" />
<txp:adi_if_mobile>
	MOBILES & TABLETS
<txp:else />
	DESKTOP ONLY
</txp:adi_if_mobile>

Whichever method you use, you can refine things even further. For example:

<txp:adi_mobile />
<txp:adi_if_mobile>
	MOBILES ONLY
<txp:else />
	DESKTOP & TABLETS
	<txp:adi_if_mobile type="tablet">
		TABLETS ONLY
	<txp:else />
		DESKTOP ONLY
	</txp:adi_if_mobile>
</txp:adi_if_mobile>

adi_mobile – tag attributes

include="type"

- a comma separated list of device types that should be reported as being mobiles. Default = “” (default behaviour).

type="type"

- force adi_mobile to report that a specified device type is accessing the website. Default = “” (report actual mobile).

useragent="string"

- override the actual user agent string. Default = “” (use reported user agent).

narrow="integer"

- define the upper limit for a “narrow” viewport. Default = 320 (pixels).

wide="integer"

- define the lower limit for a “wide” viewport. Default = 800 (pixels).

adi_if_mobile – tag attributes

type="type"

- a comma separated list of mobile types to test for, i.e. “type1,type2,type3” means type1 OR type2 OR type3. Default = “mobile” (any mobile).

width="width"

- test if viewport width is “narrow”, “wide” or an exact width (in pixels). Default = “” (do not test viewport width). adi_if_mobile tags using this option only generate output in a mobile context.

orientation="value"

- test viewport orientation. Default = “” (do not test viewport orientation). Valid values are:

  • "v", "p", "vertical", "portrait"
  • "h", "l", "horizontal", "landscape"
  • or a +/- value in degrees (0 = vertical; 90 = horizontal, turned anti-clockwise; -90 = horizontal, turned clockwise)

adi_if_mobile tags using this option only generate output in a mobile context.

disabled="type"

- test if mobile mode has been disabled. Default = “” (do not check mobile mode).

not="boolean"

- negate the condition. Default = “0” (normal condition).

adi_mobile_viewport – tag attributes

width="width"

- force the width to be a specific number of pixels. Default = “” (do not change width).

Testing & Diagnostics

The best way of testing your mobile-enhanced website is to view it on lots of different mobile phones. This not being practical there’re some other options:

  • Fake it – use the type attribute in <txp:adi_mobile />
    • <txp:adi_mobile type="mobile"/> – pretend you’re a mobile, any mobile
    • <txp:adi_mobile type="iphone"/> – pretend you’re an iPhone
  • Spoof it – use the useragent attribute in <txp:adi_mobile />
  • Display diagnostics – these are automatically stored in TXP variables:
    • <txp:variable name="adi_mobile_useragent" /> – the user agent
    • <txp:variable name="adi_mobile_viewport" /> – the viewport dimensions & orientation (w,h,o)
    • <txp:variable name="adi_mobile_width" /> – the viewport width in pixels
    • <txp:variable name="adi_mobile_height" /> – the viewport height in pixels
    • <txp:variable name="adi_mobile_orientation" /> – the orientation in degrees
    • <txp:variable name="adi_mobile_types" /> – the mobile types that have been detected

Additional information

Support and further information can be obtained from the Textpattern support forum. A copy of this help is also available online. More adi_plugins can be found here.

Version 0.2 – Download (Uncompressed) Support – TXP 4.5