Apr 3, 2009

Creating a mobile version of a web site

Mobile phones become smarter at displaying the web. According to Google Analytics reports for several web sites, the number of visitors coming from phones grows every week. Therefore having a mobile version of the web site becomes an important business advantage. In this article I describe how to easily create a mobile version of the web site using TYPO3 and TemplaVoila.
The way is fully created by me (except for one regular expression that I will mention in appropriate time). Currently it works successfully at www.calis.lv web site.


Every time when I use the "mobile user agent" term it means the same as a "mobile phone that can browse the web". There are no other specific terms in this article.

How to make a mobile version of the site

We are going to use a combination the following tools and technologies:

  • a dedicated template
  • a specially created stylesheet link
  • a patched version of TemplaVoila
  • a new TemplaVoila template for the mobile version
  • a PHP file with a user function that:
    • detects mobile agents
    • instructs TemplaVoila to use a custom template
  • TypoScript conditions to alter web site content for mobile user agents
The plan is set, let's start!

HTML template for the mobile version

The mobile version of a web site needs its own HTML template. There are several reasons for this:
  • Mobile phone screens are much smaller
  • Mobile phone memory is very limited
  • People will not like loading megabytes of flash or banners (they will have to pay it!)
  • Mobile browsing is not about beauty, it is about getting information
Given points above I can give the following requirements for the mobile page HTML template:
  • Minimum markup
  • Semantic markup (read excellent BBC pages about semantic markup)
  • No huge top images
  • Color as a page background (not an image!)
  • Search box at the bottom
Let's see these requirements in details.
Minimum markup ensures that pages load faster. Mobile phone subscribes often have to pay for traffic and often they do not have fast 3G everywhere. So if page does not load fast, most likely they will go away. Having minimum mark up speeds up page loading and gives you more users (or more potential customers if you prefer it this way).
Semantic markup is always useful but for mobile phones it is especially useful. While we will use a dedicated stylesheet for rendering the page, not all mobile user agents support CSS fully. But they will render standard elements (such as headers or lists) properly. So if lists use list markup (<ul>s and <ol>s), than they will be rendered as lists properly in all cases.
No huge top images servers to purposes: no scrolling (people hate to scroll!) and speeds up page loading. It may be okay to have a nice landscape at the top of the regular web site but why would you want it on the mobile phone? It only irritates visitors.
Color as a page background is better because color is rendered immediately. I prefer white because white is a default color and most mobile user agents render pages on a white background. So if you design a page with white font on a blue background, imagine what happens if the user agent supports text coloring and does not support background coloring (white text on a white background). With images it is even worse because image has to load separately. So use color background and prefer white background to all others.
Finally, the search box is extremely important for mobile versions. People are not going to click a lot. If they do not find information on a mobile version of your site in 2–3 steps, they will go away. So help them: put a search box on the site. Its best position is at bottom for several reasons:
  • a visitor first looks to the page (you want him look to the page, right?) and only than goes to search
  • search at the top forces scrolling (as we know people hate unnecessary scrolling)
So put the search box to the top.

Styles for the mobile version of the site

Styling is important for the mobile version. The first and the main rule: optimize for readbility, not for the fancy look. Good look is important but readability is more important for the mobile version.
When creating a mobile version of the site I recommend one trick that will help to render the page properly on most mobile user agents.
Set font size in CSS to 14px for the "body" element. This will be a "base" size for all fonts. Next use "em" measurements for all other elements. 1em will be equal to 14px, which is easy to read on mobile phone screens. 2em is twice as large and it is good enough for H1 headers. Decrease sizes by 0.2em for each other header until you come to 1em. This gives a nice presentation of headers for the mobile version of the site.
It is best to have one single stylesheet for all styles from the page (including extensions!). One stylesheet causes one HTTP request. One HTTP request for large file is faster than many request for small files. Compressing CSS is another way to speed up the loading of the page.
As a result of these optimizations you should have a single stylesheet file in your HTML template and on all mobile pages.

TemplaVoila changes for the mobile version

As you probably know, TemplaVoila can select a different template for the same page and the editor does not have to care about it. Currently this selection is limited to "print" version only. Next version of TemplaVoila will have a better way of such selection. It now exists as a patch in the TYPO3 bug tracker. This patch allows to define the template by a user function.
To apply the patch you will need shell access to the server. Go to your typo3conf/ext/templavoila directory and type this:
patch -p0 < /path/to/10781.diff
This will patch TemplaVoila.

Adding a mobile template

Next we need to make a template for the mobile web site.
The very first step is to tell TemplaVoila that we will have a new rendering type called "Mobile version". Open page properties for the root page of the web site and add the following code to the page TSConfig field:
TCEFORM.tx_templavoila_tmplobj.rendertype.addItems.mobile = Mobile version
You can change the text on the right as you see fit. This is what you see later in the template form. However keep the last word before the equals sign as is. If you really want to change it, make sure that it is 10 characters or smaller. TemplaVoila allows only 10 characters for this value.
Next you go to TemplaVoila mapping module. Click the "Add new template" button under the data structure of your page. This will show a regular TYPO3 screen to create a new record. Enter template title and file reference there. The next two steps are important to get it right. In the "Make this a sub–template of:" box, select an existing page template object. The from will ask to reload. Do it. Next another control will appear. Its title is "Select a type of rendering:". Select "Mobile version" there. The result should look like this:

Press "Save and close" at the top. This will return you to the TemplaVoila mapping module. You should now see your mobile template indented right under the regular page template:

Notice that "Render type" says "Mobile version". Now you got to templates: one os for regular visitors, another for mobile visitors. Mao the template as usual. You can leave some fields unmapped if you do not use them in the mobile version (for example, ad blocks).
We are almost there!

Detecting mobile phones

Now we need to tell TemplaVoila when to use this template. We will do it using a combination of TypoScript and a user function.
Go to fileadmin/ and create a PHP file there named user_mobile.php. Here is the content of the file:

function user_isMobile() {
  return preg_match('/(IEMobile|Windows CE|NetFront|PlayStation|PLAYSTATION|like Mac OS X|MIDP|UP\.Browser|Symbian|Nintendo)/', $_SERVER['HTTP_USER_AGENT']);

class user_mobile {

* Checks if current browser is a mobile phone. If yes, checks that
* child template given in 'value' of the configuration exists for the
* current template object. If it does, returns corresponding
* child template name
* @param array $conf Configuration for this function (parameters: conf and toRecord)
* @param tx_templavoila_pi1 $pObj Parent object
public function getChildTemplate(array $conf, tx_templavoila_pi1& $pObj) {
$result = '';
if ($conf['conf']['value'] && user_isMobile()) {
// We got a mobile browser! Check if we have a mobile TO
$toRec = $pObj->markupObj->getTemplateRecord($conf['toRecord']['tx_templavoila_to'], $conf['conf']['value'], $GLOBALS['TSFE']->sys_language_uid);
if (is_array($toRec)) {
$result = $conf['conf']['value'];
return $result;

There are two functions here. user_isMobile function will be our TypoScript condition function. It cannot be a class member, so it stays alone. getChildTemplate class function will tell TemplaVoila what template to use to render a page for the current visitor.
Next you go to the TypoScript template where you have defined your page object. Typically it looks like:
page = PAGE
page.10 < plugin.tx_templavoila_pi1
page.10.userFunc = tx_templavoila->main_page
Add new lines before this code:
[userFunc = user_isMobile]
plugin.tx_templavoila_pi1.childTemplate = USERFUNC:user_mobile->getChildTemplate
plugin.tx_templavoila_pi1.childTemplate.value = mobile
What does it do? If user comes with a mobile user agent, it instructs TemplaVoila to call the getChildTemplate function to get an alternative template. We also specify what template it will be.
You already can visit the mobile page of your site! But hold on there are certain final steps to make the mobile version better.

Clean up the HTML

By default TYPO3 produces a lot of junk in the HTML. We are going to clean it up. I recommend to put all TypoScript code below into a dedicated TypoScript template and include it to the main template. This way you can change this clean up code as you wish.
I recommend adding these clean up instructions:
config {
admPanel = 0
absRefPrefix = /
disablePrefixComment = 1
inlineStylesToTempFile = 0
pageTitleFirst = 1
removeDefaultJS = 1

plugin.tx_cssstyledcontent._CSS_DEFAULT_STYLE >
plugin.tx_felogin_pi1._CSS_DEFAULT_STYLE >
This gets rid of the most junk mark up in the output. Notice that we got rid of the all default JavaScript and we do not inline styles to the temporary files. Now if any extension tries to output inoine styles, you just copy them to our single stylesheet and add another line to this TypoScript template to get rid of those inline styles. The line will look similar to last two lines in the example above.


This is how you can make a mobile version of the web site with TYPO3 and TemplaVoila. There are some more tips and tricks (such as iPhone or Opera Mini optimizations). I will not focus on them and leave them as a home work for you.
I'd like to remind that the article may be freely linked to or quoted but it cannot be reprinted in electronic or printed media without my permission. Translations to other languages are welcome but you need to contact me first. This is the same rule as for the rest of this site.
If you liked the article, please, consider donating. Writing good articles is a big work. For example, this work took me 2.5 hours only for writing. Donations motivate to write more.


  1. Xavier PerseguersApril 3, 2009 at 3:16 PM

    As always, a very good article with enough details and screenshots. Congratulations!

    I think a tiny detail may be enhanced: having some optional parameter to force display of the mobile version even in using a standard browser, this would help creating the mobile template (it is possible to change the user_isMobile method but then it applies to all visitors)

  2. I used to have this:

    return t3lib_div::_GET('FORCE_MOBILE') || preg_match(.....);

  3. Hello Dmitry,

    Thank you for your good technical information that very interesting our customers in business companies. I think that actual Mobile actions have to check own country and I will do in next. Thank you again.

  4. Victor LivakovskyApril 7, 2009 at 2:33 PM

    Hi, Dmitry!

    Thank you a lot for this great article! :)

    Finally, I started to implement all of your instructions, described here.

    But you have one minor mistake: you describe the advantages of search box, located at the bottom of page, but as conclusion you wrote:

    "So put the search box to the top."

    And thank you one more time for this awesome work :)

  5. Great article, thanks Dmitry!

    Will try it the next days.


  6. Riccardo De ContardiMay 18, 2009 at 6:49 PM


    Your tutorial is very interesting, but...there's something I miss:

    How can I tell T3 that user_mobile.php is under /fileadmin/ ??

    Thank you and good work!

  7. Great article!

    Is it possible to use Ext: wurfl to detect the mobile phone in this case.


  8. Check out trekkertime.com. It's pretty sweet if you like traveling.

  9. Nice Tutorial but I have a problem. I did everything till Cleaning up the HTML Document. I've created the PHP-File in fileadmin/ and the copied the TypoScript in my Maintemplate. But when I browse to my site with mobile-header-data the Site doesn't change :(

    I think it's the problem Riccardo De Contardi mentioned. This PHP-file isn't used by T3.

    What should I do?


  10. Here is the part you've forgotten in your article: http://www.typo3-jack.net/typo3-english-lists-netfielders-de/19552-typo3-english-typo3-mobile-webpages-wurfl-2.html

    I try it later ;)

  11. Is it possible to go to the normal site via hyperlink when I use a mobile User-Agent?

    Not every smartphone-user wants the mobile version of the site.

  12. localconf.php



  13. I had some trouble with getting this to work, but!.. finally it seems that if you have included templavoila like this:

    10 = USER

    10.userFunc = tx_templavoila_pi1->main_page

    It will not work without setting page.10.childTemplate = mobile in the condition [userFunc = user_isMobile]

    BUT if you use

    10 < plugin.tx_templavoila_pi1

    10.userFunc = tx_templavoila_pi1->main_page

    instead of the 10 = USER ... method, it will just work out of the box.

    You should also remember to include the user_mobile.php userfunc in localconf.php

  14. Awesome post, if anyone wants a bit more info on the subject (or something to link their clients to), I just finished a lengthy post on the subject:


  15. If TypoScript template looks like

    page = PAGE

    page.10 = USER

    page.10.userFunc = tx_templavoila_pi1->main_page

    page.10.disableExplosivePreview = 1

    (templavoila default), you can use

    page.10.childTemplate = USERFUNC:user_mobile->getChildTemplate

    page.10.childTemplate.value = mobile

  16. Дмитрий, скажи пожалуйста, как использовать REALURL для мобильной версии сайта, которая размещена по другому домену.


  17. Thanks for the great tutorial. I already implemented it, but one important thing is missing: How can I let the user force to use the full desktop website if he wants to? A link at the bottom is needed for this, but the "user_isMobile()" function has to be rewritten i think.

  18. Which prescribe the patch -p0 < /path/to/10781.diff
    More info please.