How to create a mobile WordPress theme with jQuery Mobile

Last month, jQuery Mobile was released. This tool allows you to easily create mobile websites and web apps. In this tutorial, I'll show you how to create a mobile-optimized WordPress theme.

Here is what we’re going to build together today. Click the image to view the live demo.

Step 1: Getting files

We could have created our theme from scratch, but there’s no need to reinvent the wheel when there’s tools that can help you save lots of time. The tool we’re going to use is called Blank Theme. It is a functional WordPress theme, but without any styling. That way, it can be used as a starting point for creating your own themes. For example, I’ve used Blank Theme to create the current Cats Who Code theme.

Blank Theme has been created by Chris Coyier and it can be downloaded here. Get a copy and unzip it on your server or hard drive: We’re going to start. Optionally, open the style.css file and modify the theme name to fit your own needs.

Step 2: Header and Footer files

As we’re going to create a theme that will rely much on jQuery, the first thing we have to do is to link to jQuery and the jQuery Mobile files. You can either download the files individually and link them to the theme, or you can use jQuery’s CDN and link the online versions to your theme. I personally prefer linking to the online version, but it’s up to you.

Open the header.php file from the Blank Theme directory, and insert the following code to link to jQuery Mobile, within the <head> and </head> tags:

<link rel="stylesheet" href="" />
<script src=""></script>
<script src=""></script>

Once done, the required jQuery files are now linked to our theme. But we’re not done yet with header.php. As jQuery Mobile uses HTML5, we have to modify the doctype. Replace the first 6 lines of the file with:

<!DOCTYPE html>

Then, scroll down to the bottom of the file and locate the <body> tag. Replace everything from the <body> tag until the end of the file by the following:

<body <?php body_class(); ?>>
    <div data-role="page" data-theme="b" id="jqm-home">
        <div data-role="header">
            <h1><?php bloginfo('name'); ?></h1>

        <div data-role="content">

We just dove in jQuery Mobile with the code above. What? We haven’t even wrote a single line of JavaScript! That’s right. jQuery Mobile doesn’t need you to write any JavaScript. All it needs is some <div> tags with the proper data-role attribute.

As an explanation, take a look at line 3 of the code above. Have you noticed the data-role="header"? It describe a header bar. If you save the file and view your theme right now, you’ll notice a header bar on the top of the screen, with your blog name.

Now, save header.php and open footer.php. Replace its content by:

        </div><!-- data role content-->

        <div data-role="footer" class="ui-bar">
            <a href="#jqm-home" data-role="button" data-icon="arrow-u">Up</a></div>
        <?php wp_footer(); ?>
    </div><!-- data role content-->

This simple code will insert a footer bar to our theme, with a button that will scroll up to the header when the user will tap on it. Did you noticed the data-icon attribute? It allows you to specify which kind of icon you want. In our case, we want an up arrow, but there’s lots of different icons you can use.

Step 3: The homepage

Now, let’s code our homepage. As we’re building a theme for mobile devices, we do not need anything fancy. Let’s build a list of our recent posts. To do so, open the index.php file, locate the loop, and replace it by the following code:

<ul data-role="listview" data-inset="true" data-theme="c" data-dividertheme="b">
    <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
        <li><a href="<?php the_permalink() ?>"><?php the_title(); ?></a></li>
    <?php endwhile;endif ?>
<?php include (TEMPLATEPATH . '/inc/nav.php' ); ?>

Save the file and take a look to your theme: It looks great! We now have a list of posts on our homepage. Once again, we have a very good looking list, with some nice transition effects, without coding a single line of JavaScript. That’s the magic of jQuery mobile.

The list is created by using the data-role="listview" attribute on the unordered list. The other attributes specifies the appearance of the list. Want to experiment a bit? Simply replace data-theme="c" by data-theme="b" and see what happens.

Now, modify the loops of the search.php and archive.php files like we did with index.php.

Step 4: Post and pages files

By default, the single.php and page.php files from the Blank Theme looks good in our mobile version, so we do not need to modify those files. Though, we can do something to enhance user experience: Mask the comments by default, and show them only if the user decides to. This can be done extremely easily using jQuery mobile.

Open comments.php and locate line 15. Insert the following line:

<div data-role="collapsible" data-state="collapsed">

Then, go to line 31 and insert a closing </div> just before the else statement. Save the file and have a look at one of your posts: Comments are now masked by default, and a tap/click on the bar display them. If you prefer to show the comments by default, no problem: simply remove the data-state="collapsed" attribute. That’s all we need to create a collapsible content block.

Did you noticed that on posts, the header bar is showing a “Back” button? A click/tap on it will take you back to your blog homepage.

Step 5: Implementing search

Right now, we have a theme fully optimized for mobile devices. But it is missing something important: An easy to access search bar. Open your searchform.php file and replace its content by the following:

<form action="<?php bloginfo('siteurl'); ?>" id="searchform" method="get">
    <div data-role="fieldcontain">
	    <input type="search" name="s" id="search" value="" />

After you saved the file, reopen index.php and include the search form between the get_header() function and the unordered list which contain our posts:

<?php include('searchform.php'); ?>

Our homepage now has a working search form. Right now, our theme is done and we can use it on a production site.

Step 6: Final touches

Of course, even if the theme we’ve built is perfectly functional, there are still a lot of things that can be done to enhance its look and functionality. For example, I have noticed that the search field is smaller than the list items. In order to make the search field as wide as the list items, paste the following in style.css:

    width:96% !important;

That’s all for today. I hope you enjoyed this tutorial. If you want to download the finished theme, just click here.

Also, I just redesigned my other blog Cats Who Blog so don’t hesitate to visit it or grab the RSS feed to read it later. The blog is now 100% focused on tools to make your life as a blogger, developer or designer easier. Enjoy!