If you look at the System > Configuration > General > Design -> Package and Theme sections, you’ll see that Magento provides “Add Exception” buttons most of the configuration parameters available. There is also a cryptic caption saying: “Match expressions in the same order as displayed in the configuration.”
But what does it mean? And what can we do with this?
Well, if you’re adventurous and hike into the code behind the exception options you will realize that Magento takes a regular expression string in “Matched Expression” and will compare it with the browser user agent, applying the “Value” set as the one to use instead of what is set for the default if it finds a match.
In other words, if the regular expression matches with the browser user agent apply the design exception set.
In yet more words, you can use this to check what browser customers are using to access your store and set a different package / template / skin / layout / theme accordingly. So, if you want to serve up a different theme for mobile browsers, this is where the exceptions come in handy.
Let’s look at how to set this up so Magento serves the iPhone theme for mobile device customers:
Here is the full contents of the “Matched Expression”:
iPhone|iPod|BlackBerry|Palm|Googlebot-Mobile|Mobile|mobile|mobi|Windows Mobile|Safari Mobile|Android|Opera Mini
This may not be an exhaustive list of mobile browser agents but you get the idea. To check for your specific user agent, you can use: whatsmyuseragent.com.
Bear in mind when entering strings that they are case sensitive.
So what the example in the screenshot is saying is: “If the user agent is one of the listed ones, serve up the iphone design that ships with Magento, otherwise just use the default”.
Depending on where you add your exception, you can create a different layout or skin or complete theme for your audience who use different devices to get to your site.
For example, you could have a cutting edge design as your default theme but offer an alternative, cut-down version for the odd IE6 user.
For the most part, however, you will use this feature to serve a mobile optimized version of your design.
Finally, what does that cryptic caption then mean? Well, it just means that if you have several exception rules, they will be matched and applied in the order they are listed.
Post Update:
If you have a good regular expression matching mobile devices or have implemented an interesting browser exception, please do share it in the comments.
Originally published on magebase.com. Copyright © 2010 Magebase - All Rights Reserved.
Proud members of the 
Nice simple explanation – this really hasn’t been documented so well by the Magento team.
How would this work for IE6? What would the user agent be in that case? I think it would be nice to just redirect IE6 users to one of the standard themes, maybe the blank one, and show everyone else your custom theme – would save a lot of time and effort – I know this can be done with conditional statements but this would be even easier and require no extra markup.
@Sam
Say you have “yourtheme” set in the Themes / Default field and you want IE6 users to be served the default Magento theme. You could plug into Matched Expression:
MSIE 6.0anddefaultin value.Note this will also match Opera 8 and 8.5 according to the user agents on this page: http://whatsmyuseragent.com/CommonUserAgents.asp
You can avoid matching Opera 8/8.5 with this regex:
MSIE 6.0(?!.*Opera 8.*)Just wanted to share with everyone that i was able to get this to work on my iphone but not the iPad by taking out the “Mobile” exception from this list.
The final matched expressions would be: iPhone|iPod|BlackBerry|Palm|Googlebot-Mobile|Mobile|mobile|mobi|Windows Mobile|Safari|Android|Opera Mini
Just put “iP” for iPhone, iPad, iPod… it works for me.
Sorry, looking at my original post I realized I made an error. The only exception that needs to be taken out of the list is the “Mobile” exception. The one with the capital “M”.
The (revised) final exception would be: iPhone|iPod|BlackBerry|Palm|Googlebot-Mobile|mobile|mobi|Windows Mobile|Safari|Android|Opera Mini
Notice the “Mobile” is not in there.
I have this working on Enterprise Edition 1.8 and 1.9.1.1
Taking out Mobile also excludes Nokia Belle browser compatibility!
thanks for the post, with google clogged up with info on the new magento mobile app it’s been hard to find a decent how to guide, for me an optimized mobile site will work better than an app and is a lot cheaper.
First of all, sorry for my english, i added
|Nokia|SymbianOS
al the list of exceptions. I tested in my Nokia C5 and works fine
Can I be the one moaning “It doesn’t work”??? You’d think it’s quite straightforward to add the exeption, but somehow something goes wrong… Are there any reasons why this would fail? Tested on a Desire (Android) and iPhone.
@Piet given the amount of info you supplied, my questions are:
– have you cleared the cache if enabled to activate your configuration change?
– if yes, what exactly did you do – describe your steps (and Magento version).
I just downloaded the latest magento version (1.5.1.0) and installed it with the sample data package. Selected 3 languages somewhere (can’t find this option anymore and doesn’t seem to work anyway) that showed up on the basic template.
Installed a template via copying it with ftp and select it in settings -> design and then add change or something similar. then added the exeption as indicated in the picture. Have been trying to put in the exception @ template and skin etc. as well.
I do notice that when i change the language, the template on my android phone indeed changes! How could this be related to that?
If you have set the Current Package Name under the Package section to anything other than ‘default’ then you will need to add a design exception there too. It that case, the exception Matched Expression field should contain the same value for the various devices but the Value field should be default.
The iphone theme is under the default package. Also, make sure you actually have the iphone theme under
app/design/frontend/default/iphone.Hi Robert,
I couldn’t get this to work because I had a non-default theme and had set up a design rule under System > Design to make the theme live. I deleted this and put the name of my non-default theme in the ‘Default’ Field of your screenshot.
This might help anyone else who had forced their non-default theme via System > Design.
Thanks
Hi Robert,
Thanks for very nice explanation. I was looking for this forever.
I’ve done exactly the same as above and cleared the cache but still no result on my windows mobile (HTC HD). I tried opera mini 5, 9, 10 , WM IE.
Thanks for your help.
@Aria please check my previous comment reply to Piet. You may be using a non-default package? Unfortunately, the details you have provided are not enough to help you.
Also, having done a quick google search on Window Mobile user agent, looks like the identifying string is something like:
Mozilla/4.0 (compatible; MSIE 7.0; Windows Phone OS 7.0; Trident/3.1; IEMobile/7.0) Asus;Galaxy6
So, I suggest adding ‘Windows Phone’ and/or ‘IEMobile’ (without the quotes) in the list of Matched expressions.
Hi Robert, I’ ve indeed a non-default package . First it didn ’ t matter if I use default or non-default one . Obviously if you have an inactive non-default package you still need to add exception overall under package section (template /skin/layout/ default).
I use ‘Windows CE’ and it works fine with different browsers on my device.
It’s now working many thanks to you.
I was wondering if there is a way to allow for people to opt BACK to the regular site if they dont want to use the mobile site or have it forced on them for that experience? Do you know how to do this?
+1 for me!
I am wondering the same thing. Does anyone know how to do this? Is this possible with the user agent detection magento uses?
@KidA, @clark
This is something I was going to research myself as well since we are in the process of designing our own mobile theme. However, at this stage, I can’t answer this question. In theory, I guess, you could override the module where the exceptions are checked and add your own switch processing depending on some flag set in the customer session cookie.
I see that the AheadWorks iPhone Theme provides a switch to the desktop version of the site but I’m not sure how it works. Seems as if they have their own controller that provides the switch functionality.
A solution for switching between mobile and desktop, and its free! http://www.4mgstore.com/blog/2011/07/06/magento-mobile-version/
Just came across this article while looking the functionality to serve a mobile version of magento.
It would seem that this would be possible to use Detect Mobile Browser to accomplish what you are trying to do?
I’ve been looking for information about how to include Android phones and exclude Android tablets. Google says you should exclude Android if the user agent doesn’t include ‘mobile’ in it.
http://googlewebmastercentral.blogspot.com/2011/03/mo-better-to-also-detect-mobile-user.html
Is it possible to detect “android” with “mobile”? If I include “Mobile” in then it also detect iPad.
iPad running iOS 3.2 user agent string
Mozilla/5.0 (iPad; U; CPU OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B334b Safari/531.21.10
http://developer.apple.com/library/safari/#documentation/AppleApplications/Reference/SafariWebContent/OptimizingforSafarioniPhone/OptimizingforSafarioniPhone.html#//apple_ref/doc/uid/TP40006517-SW3
@toshi You have to set up your regular expression so that you cover your desired devices. You may need to devise a more complex RegEx to match ‘mobile’ only if there is no iPad string also.
According to this page, Samsung Galaxy Tab contains both “Android” and “Mobile” in the user agent. There aren’t easy ways to separate Android phones and Android tablets… Hmmm.
http://stackoverflow.com/questions/5341637/how-do-detect-android-tablets-in-general-useragent
This does not work for me. I have tried a whole bunch of combinations but nothing works (no theme change). I’ve tried something like this (http://www.magentocommerce.com/boards/viewreply/134187/) and it still doesn’t work. I’ve tried to change the Package name and it at least switches but does not pick up ANY css or images???
I’m so confused…is it because I’m on a subdomain????
/skin/frontend/pro/iphone is where the package sits…
You say your skin files are under:
/skin/frontend/pro/iphoneso I assume you are using Magento PE (Professional).Where are your iphone theme design files? Are they under:
/app/design/frontend/default/iphone/or/app/design/frontend/pro/iphone?If you copy the design files under the pro theme package, then you should be able to make it work. Also, refer to my previous comment here: http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-1073
Yes, Professional. Thank you – either the person who installed Magento didn’t include/deleted the iphone template or it simply did not come with it. I have downloaded CE and copied over the iphone template (to get started from). I knew there was iphone folder in Skin but I did not know about the App one. Thank you again – lifesaver!
i have used the expression iPhone|iPod|BlackBerry|Palm|Googlebot-Mobile|mobile|mobi|Windows Mobile|Safari|Android|Opera Mini|Nokia|SymbianOS as exception and iphone as a value..i have setup the iphone theme. But my problem is that It WORKS WITH NOKIA PHONE BUT SHOWS THE FULL WEBSITE VERSION IN iPhone .
Please help
You should check the user agent your iPhone reports. Use the link in my earlier comment: http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-219
Hey, Thanks so much Robert! You saved my day.
Thanks a lot Robert …works fine for me now 🙂
Thanks a lot Robert , working like a charm 😉
Hi Robert and everyone else,
Big thanks for this one and the ‘mobilize’ tutorials. Very clear and as someone as already noted, very handy as there almost none around of the same quality.
I have a problem relating to the UAs in the expression as both iPad (Safari desktop iPad mode) and desktop Safari both show the iphone theme with the suggested string. I tried taking out ‘Mobile’ as Clark noted above but that didn’t help. Could it be an update in UAs that are now creating this problem or is the Safari simulation mode not to trust?
Thanks a lot in advance
Peter
[…] oder verschiedene Devices im Cache halten will? Ein solcher Anwendungsfall sind z.B. die sog. Design Exceptions in Magento, mit denen sich abhängig vom User-Agent (Browser) das Theme unter System/Konfiguration/Web ändern […]
I’m taking over a magento project on which previous developers had already worked.
Should there be references to the custom stylesheets in the head.phtml file at all? It seems like you would only set that within the backend.
Also, I got the above working in a limited way, but it loads a mobile page for BOTH desktop and mobile browsers. It doesn’t seem to detect one or the other.
Ideally, there shouldn’t be references to custom style sheets in head.phtml, all CSS should be added using the:
<reference name="head"> <action method="addCss">... </reference>in
local.xmlIt’s difficult to know what’s going wrong in your setup without knowing your configuration, but the approach from the article definitely works, so you may need to revisit your settings.
Hi friends,
i need to use diffrent template like:iphone for mobile browser and use default template for system browser, what exactly i should do, i used this solution but it’s not working,
are you sure if i use this solutiob my problem will short out?
my mobile template name ie mobileredlily and name of my default template is redlily, after putting exception in default tab in value section i have to put template name or what???
i cant understand please help me
@rakesh
The instructions here are as clear as they can be. There is nothing else I can add. Also, please read the comments as there may be additional information that can be helpful. One thing to check is if your theme is under a custom package name, ie: app/design/frontend/[my-package]/[my-theme]/. In that case check this comment here: http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-1073
Rakesh,
Make sure you’re following the instructions above well. Also, in my case, I was missing the entire design template directory. Make sure you have both! (check out http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-1660)
Hi,
I have an issue. I’m using a custom package which is located in
The only way I have to make this theme work is going into my System/Design and Add Design Change otherwise it will stick to the default design and I think is supposed to be that way.
The problem is that when I followed your instructions and I added these exceptions, technically nothing happened.
It only changes the order of the very top menu (My Account | My Wishlist | My Cart | Checkout | Log In) and the bottom menu and that’s all, everything else looks the same.
Can you help me out to figure what I’m doing wrong?
Thanks!
You are using a design package (blank) and your theme is under that. See my comment here about this situation: http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-1073
[…] we recently learned, it’s pretty straight forward to redirect your mobile visitors to a mobile-optimized theme, the […]
Thank you, It’s useful to me.
Thank you, Its work for me as well.
It wasn’t working initially, As either i may not read it properly or i was trying wrong. I think it would be helpful to someone that if i say how did i make it.
System > Configuration > General > Design -> Package and Theme sections
Enter the following value’s in to the all “Template, Skin, Layout, and Default” Section (Not only the Default section)
Matched Expression: iPhone|iPod|BlackBerry|Palm|Googlebot-Mobile|Mobile|mobile|mobi|Windows Mobile|Safari Mobile|Android|Opera Mini
Value: iphone
For mobile matching I like to use http://detectmobilebrowsers.com/. I just think it catches more phones and it is updated too. Since they don’t have just a plain regular expression option i just modified one of the others a little and it seems to be working great.
Matched Expression: (?i)((android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows (ce|phone)|xda|xiino)
Value: iphone
I was able to so this on a default install but was unsuccessful in seeing a change on a customized Magento site using the same technique. Anything I should be considering that I might have missed?
I should also add that I’m actually using Magento Enterprise ver. 1.12.0.1.
Having the same problem as Andrew – It switched fine if the default template is chosen but as soon as I swap to another template then it doesn’t work?
Please read the comments, setting the design exception for non-default packages is covered here: http://magebase.com/magento-tutorials/magento-design-exceptions-explained/comment-page-1/#comment-1073
Is it possible to do a mobile version of my website that useMagento community ver. 1.3.2.4 or I should upgrade to achieve that goal?
Thanks
I’m a newbie at this but what are the spec, dimension of the template I should let my designer do for the mobile theme?
I’ve enabled the Magento iPhone Theme but it seems there is some kind of bug with Google Analytics. After the enabling all mobile visitors are provided with the iphone theme but they’re NOT TRACKABLE anymore in Google Analytics
Worth noting that this is a regex match. It is also case sensitive. You can see the code at
I wanted to try to get as many mobile browsers as possible, but exclude Android tablets and iPads. Assuming that Android tablets don’t have ‘Mobile’ in the UA string, I am trialling this one:
Also worth mentioning that you could split them into multiple exception lines to make it easier to understand or use with complex regex.
The other really cool thing that is often overlooked is that if you theme is mostly responsive anyway, or you just wanted to include a separate CSS file, you don’t have to overload the entire theme, just the skin or specific template files. While it’s simple it isn’t immediately obvious that you don’t always need an entirely different theme.
There’s a really good resource for UA pattern matching here:
https://gist.github.com/dalethedeveloper/1503252
Thank you Robert for the great post….Dane this really helped me…Thank you
Hi guys,
I am using Magento version 1.3.2.4. i am planing to use IPhone theme for mobiles. But it is not working for this version. I follwed all procedures. Could u guys help me for this issue. Thanks in advance.
[…] Magento Design Exceptions Explained Or How To Serve … – Founder and Technical Director of LERO9, a web agency specializing in Magento and WordPress design and development. I launched Magebase in April, 2010 and am its …… […]
Who knows how to set this exception via PHP in Magento?
Hi,
I have this question, I can use magento from my cellphone? is a htc10, sorry i know that is a stupid questions, bit I’m so new in this format. Sorry for that.