This is the documentation for concrete5 version 5.6 and earlier. View Current Documentation

Originally posted by andrew at


In the world of smartphones, the iPhone was a game-changer. We can debate the relative merits of the various players, but it can't be denied that, when it debuted, the iPhone brought a lot to the table. Nowhere is this more apparent than when using Mobile Safari. The world finally had a usable, standards-compliant mobile browser.

However, something interesting occurred almost immediatley after the iPhone was released. Web designers began creating iPhone-specific websites. These websites use stylesheets (and sometimes entire images and content) to tailor their form factor and presentation specifically to Mobile Safari. They will also frequently ape the iPhone aesthetic. 

Initially, this puzzled me. If web designers are building standards-compliant websites with decent liquid layouts, Mobile Safari displays them quite well, and pretty quickly. For example, this site, when viewed on Mobile Safari, displays impressively well, with no tailoring toward Mobile Safari in particular. 

However, as I started thinking about it, I realized that most websites aren't exactly like your garden variety blog. They have grown to include lots of JavaScript, images, and extraneous cruft that can slow down rendering on the iPhone's more lightweight processor. In these cases a mobile version can make a noticeable difference – even though the regular website could still easily be viewed. 

Enter c5touch.

With all of this in mind, I present to you c5touch, a Mobile-Safari-optimized concrete5 theme. 

footer image

c5touch is based on an impressive Wordpress theme named WPTouch. If you run a Wordpress blog, I highly recommend it.  c5touch doesn't do half of what WPTouch does. This is partially because Wordpress, by its very nature, is a much more structured system than concrete5. But it's also because c5touch is young, and is being made available more as a simple exercise in what's possible in concrete5 with a little bit of tweaking. I would love for some enterprising soul to extend it in further directions. Consider this initial offering a proof of concept.

Download, Installation and Setup Instructions

concrete5 makes it easy to install and activate themes. c5touch is a little bit different, however, for one reason: it's not the only theme you're going to have on your site. c5touch compliments your site's main theme. You install c5touch, but you leave your site's main theme (or themes) activated, and add some code to your site to enable the usage of c5touch when concrete5 detects your site is being requested by Mobile Safari.

Before You Start

1. Download c5touch

Grab c5touch from here.

2. Install c5touch on your site.

FTP c5touch to the local themes directory on your site. Unzip it and install it through the dashboard. Don't activate it! (For more information on how to install a theme in your concrete5 site, check out this link)

3. Modify concrete/libraries/view.php

As of this writing, the latest stable release of concrete5 is This tutorial requires a change to the core which have not yet been released. You can, however, add the change to the core file directly, confident that it will eventually be released.

First, locate the comment that says

// Extract controller information from the view, and put it in the current context

And add the following line above, so your source looks like:

Events::fire('on_start', $this);
// Extract controller information from the view, and put it in the current context

4. Enable application events for your site.

Enabling support for concrete5's application events allows site developers to hook custom application and website code into common concrete5 actions, without having to modify the core. These must be enabled first, however. Add the following line to config/site.php:

  1. define('ENABLE_APPLICATION_EVENTS', true);

5. Hook into the global "on_start" event.

The on_start event (which we added to older concrete5 versions in step 3) is run by the view library at the very beginning of a page rendering session. This is before a theme or controller is loaded. It is here that we wish to check which browser is requesting our site and, if necessary, switch to our iPhone-optimized theme.

First, create a file named site_events.php in the config/ directory. Then, paste the following code into this file.

Events::extend('on_start', 'ThemeSwitcher', 'checkForIphone', 'libraries/theme_switcher.php');

This code may look complex, but it's fairly simple. The first argument, "on_start" is simply the name of the concrete5 application event we'd like to hook into (note, this is separate from controller-level or page-type-level events.) The second argument, "ThemeSwitcher" is the name of a class we're going to call a method in. The third argument, "checkForIphone" is the method in the ThemeSwitcher class that we're going to call. Finally, the fourth argument tells us where we can find the ThemeSwitcher class.

6. Create the ThemeSwitcher class at the proper location.

Now we need to create the proper class file at the location specified in step 5. Create an empty file in your local libraries directory, named "theme_switcher.php" Then, paste these contents into the file (minus the line numbers.)

  1. <?
  3. class ThemeSwitcher {
  5. public function checkForIphone($view) {
  6. if (strstr($_SERVER['HTTP_USER_AGENT'], 'iPhone') ||
  7. strstr($_SERVER['HTTP_USER_AGENT'], 'Android') ||
  8. strstr($_SERVER['HTTP_USER_AGENT'], 'webOS')) {
  9. $iphone = PageTheme::getByHandle('c5touch');
  10. $view->setTheme($iphone);
  11. }
  12. }
  14. }

This is code is quite simple. It simply checks to the current request's user agent to see if it contains keywords that indicate the user is using a mobile webkit device. (Update: This now includes Android and Palm's webOS.) If so, we grab the theme object for the c5touch theme and render the view (which is passed as an argument to the method) using that theme.

And that's it! Bask in the glow of iPhone compatibility. 

Additional Notes and Other Helpful Tips

Now, you'll probably notice that there is still a bit of work to be done to get your site to look top-notch on the iPhone. c5touch is a starter theme, but you'll still likely have to create page types and some custom style rules to really get everything to look great. Here are some things I've done on to go the extra mile.

1. Add some of your main site's css to the iPhone optimized theme by using c5touch/site.css.

Your site may look somewhat drab. Copy some of the block-level and reusable styles that you're using throughout your site from your main theme, into the c5touch site, using the empty site.css stylesheet. For example, all my masthead images have drop shadows and some other effects applied to them. I copied this from my main theme into my iPhone-optimized theme.

2. Scale images

While my text looked great when I started using c5touch, the images within the content space were much too large, and looked silly. So I'm using the following custom code in my image block view template to scale them down.

In your site's empty root-level blocks/ folder, create a folder named image, and copy concrete/blocks/image/view.php into blocks/image/. Then, open it in a text editor and make the changes below:

  1. <div class="main-image">
  2. <?
  3. $v = View::getInstance();
  4. if ($v->getThemeHandle() == 'c5touch') {
  5. $ih = Loader::helper('image');
  6. $ih->outputThumbnail($f, 275, 1000);
  7. ?>
  8. <? } else { ?>
  9. <div><img src="<?=$f->getRelativePath()?>" class="footer-image"
  10. width="<?=$f->getAttribute('width')?>" height="<?=$f->getAttribute('height')?>"
  11. alt="footer image" /></div>
  12. <? } ?>
  14. <? if ($altText) { ?>
  15. <div class="main-image-caption"><?=$altText?></div>
  16. <? } ?>
  18. </div>

This code ensures that, when images are displayed in the c5touch theme, they will be scaled down, using concrete5's autoresize algorithm (which takes care of caching, transparency, etc...)

3. Experiment!

This tutorial is meant as a starting point. Currently, c5touch is by no means a drop-in solution. If there's enough interest, I'll investigate expanding this into a concrete5 package. This would be ideal, as the package format could automate all of the various steps that currently have to be performed by a developer. But in the meantime, I'd love feedback from anyone, as well as suggestions. I hope this proves useful. 

Loading Conversation