Mobile-ize Your CakePHP App: Part 1

Christmas is fast approaching, so, as a gift to my readers (and myself; this weblog is a kind of notebook to me), and to save my weblog from neglect, I'll be writing a short series of posts on how to create a mobile version of your CakePHP app.

I've always been bragging to my peers how awesome CakePHP is, and so now I'm writing a short tutorial on how to create a mobile-friendly version of a CakePHP app. I promise to make this as easy as possible. If you're ready to start the journey, and you have a CakePHP 1.3 app to roll with me, then here we go. :)

Step 1: Prepare Your CakePHP App

In your config/routes.php file, add the following lines, just after your homepage route:

Router::connect('/m', array('controller' => 'posts', 'action' => 'index', 'mobile' => true));
Router::connect('/m/:controller/:action/*', array('controller' => 'posts', 'action' => 'index', 'mobile' => true));

What we did above was to define that you want a mobile version of your homepage and all other controllers/actions by passing 'mobile' => true as a named parameter. In this case, we used 'm' as the url prefix that turns on the named parameter.

I use posts/index as my homepage, but you can change it to whatever suits your application.

Step 2: Add Detection Code In App Controller

We will need to add some sort of detection code in the app controller, primarily to do two things:

1. Check if the user visits via a mobile device, and redirect to the mobile site accordingly.
2. Let the user choose if he wants to visit the "normal" site, while on a mobile device or browser.

Before adding the code below, do not forget to add the RequestHandler component in your AppController's $components array. I also added a custom property named $mobile in my AppController, so I don't have to retype the RequestHandler::isMobile() detection throughout my app.

// Add the RequestHandler component to the $components array. We will use the isMobile() method.
var $components = array('DebugKit.Toolbar', 'Session', 'Auth', 'RequestHandler', 'Email', 'Cookie');

// This property will hold a value if the user is viewing the mobile version of our app.
var $mobile = false;

Add the following code to your AppController's beforeFilter() method.

$this->mobile = !empty($this->params['mobile']) ? true : false;

// Redirect if mobile a mobile device, not yet in the mobile site, and doesn't have the cookie yet.
$visited = null;
$visited = $this->Cookie->read('Info.Visited');

// Not on the mobile site, is a mobile device, and a first-time visitor
if (!$visited) {
    $this->Cookie->write('Info.Visited', 1);
    
    if (!$this->mobile && $this->RequestHandler->isMobile()) {
        $this->redirect(array('controller' => 'posts', 'action' => 'index', 'mobile' => true));
    }
}

$this->set('mobile', $this->mobile);

if ($this->mobile) {
    $this->layout = 'mobile';
}

As you may have noticed, we created a cookie to help us determine if the visitor is a returning user from a mobile device, and has visited the mobile site at least once, so we don't have to redirect him over and over again. I also created a custom layout named mobile.ctp for the mobile version of my app.

Usually, you only want to create a mobile-friendly theme for the public pages of your app, so if you have conditions in your beforeFilter that test if the user is on an admin route, or something similar, then you would want to add the code illustrated above inside the non-admin portion of that test.

I'll be closing this post for now, so you can still have enough space in your memory to digest what we learned here today. Stay tuned for the next part of Mobile-ize Your CakePHP App.