Documentation Developing for Mobile Phones and Tablets

Developing for Mobile Phones and Tablets

Overview #

All WordPress.com sites have a theme for mobile devices. See Mobile Themes > Support — WordPress.com for general support info.

↑ Top ↑

Custom Mobile Themes #

If you would like to use custom mobile themes, we can:

  • Set a mobile-theme which will be used for mobile devices.
  • Set a theme specifically for the iPad (otherwise treated as a desktop.)
  • Set a theme for all Tablets (excluding the iPad.)

You can grab our custom mobile themes with an SVN checkout.

svn checkout https://wpcom-themes.svn.automattic.com/minileven/

If you only need to customize the look and feel of the existing mobile themes, it’s a good idea to create a child theme instead of replicating the existing theme code.

When you have a theme ready, send a zip back to us for review.

↑ Top ↑

Shared Functionality #

Note that with mobile themes, we do not load the main theme’s functions.php file. This can often lead to compatibility and styling issues.

If there is common functionality between the main and mobile themes, instead of duplicating the content, we recommend sharing it.

You can do this one of several ways:

Child Theme of the main theme #

You can build a child theme of the main theme and override styling and any other hooks necessary.

↑ Top ↑

functions-shared.php / functions-mobile.php #

You can add a file called functions-shared.php in your main theme that is loaded from both and contains any shared functionality. Alternatively, you can add a file functions-mobile.php in your main theme and load only the plugins/files you want for mobile:

In your mobile theme’s functions.php:

require_once( wpcom_vip_theme_dir( 'main-theme' ) . '/functions-shared.php' );

In your main theme’s functions-shared.php:

// This plugin is used and loaded on desktop and mobile themes
require_once( __DIR__ . '/plugins/bearify/bearify.php' );

↑ Top ↑

Targeting Mobile Visitors #

If you want to target mobile users for any reason, you can use WordPress.com’s jetpack_is_mobile() function.

function jetpack_is_mobile( $kind = 'any', $return_matched_agent = false ) 

Where kind can be:

  • smart
  • dumb
  • any

You can also use:

  • Jetpack_User_Agent_Info::is_ipad()
  • Jetpack_User_Agent_Info::is_tablet()

Views from mobile devices are batcached and to make sure things work as expected, please let us know before including any additional server-side logic (PHP) in your code.

These are loaded for you automatically.

↑ Top ↑

Mobile to Full Desktop Theme Switching #

If you’d like to allow your users to switch from the mobile theme to the regular theme, you can create a link similar to:

View <!--?php bloginfo('title'); ?--> <a href="<?php echo esc_url( add_query_arg( 'ak_action', 'reject_mobile', home_url() ) ); ?>">Regular Theme</a>

For the other way around, use ?ak_action=accept_mobile.

This code is already included in the default mobile themes.

↑ Top ↑

Local Testing #

The bulk of our mobile handling code is available via the Jetpack Mobile module. To use it with a custom mobile theme, you can add your mobile theme in the VIP themes repo (wp-content/themes/vip/) and use a snippet like a following in a mu-plugin to toggle the loading of your custom theme:

if ( ! defined( 'VIP_CUSTOM_MOBILE_TEMPLATE' ) )
	define( 'VIP_CUSTOM_MOBILE_TEMPLATE', '' );

if ( ! defined( 'VIP_CUSTOM_MOBILE_STYLESHEET' ) )
	define( 'VIP_CUSTOM_MOBILE_STYLESHEET', '' );

add_action( 'jetpack_modules_loaded', function() {
	if ( '' == VIP_CUSTOM_MOBILE_TEMPLATE || '' == VIP_CUSTOM_MOBILE_STYLESHEET )
		return;

	if ( ! jetpack_check_mobile() )
		return;

	// Remove Minileven's path overrides
	remove_filter( 'theme_root', 'minileven_theme_root' );
	remove_filter( 'theme_root_uri', 'minileven_theme_root_uri' );

	add_filter( 'jetpack_mobile_stylesheet', function( $stylesheet, $theme ) {
		return VIP_CUSTOM_MOBILE_STYLESHEET;
	}, 99, 2 );

	add_filter( 'jetpack_mobile_template', function ( $template, $theme ) {
			return VIP_CUSTOM_MOBILE_TEMPLATE;
	}, 99, 2 );
} );