Sitefinity Toolkit: Mobile Device Detection

IMPORTANT UPDATE FOR USERS OF SITEFINITY TOOLKIT 1.2

There is a compatibility issue between the Mobile Foundation library used for mobile detection and the Sitefinity Administration Login that could not be resolved. The Mobile Detection Module can still be used but the Mobile Foundation must be DISABLED in web.config by commenting out the related sections in web.config:

<!-- 
<sectionGroup name="fiftyOne">            
<section name="log" type="FiftyOne.Foundation.Mobile.Configuration.LogSection, FiftyOne.Foundation" requirePermission="false" allowDefinition="Everywhere" restartOnExternalChanges="false" allowExeDefinition="MachineToApplication"/>            
<section name="redirect" type="FiftyOne.Foundation.Mobile.Configuration.RedirectSection, FiftyOne.Foundation" requirePermission="false" allowDefinition="Everywhere" restartOnExternalChanges="false" allowExeDefinition="MachineToApplication"/>            
<section name="wurfl" type="FiftyOne.Foundation.Mobile.Detection.Wurfl.Configuration.WurflSection, FiftyOne.Foundation" requirePermission="false" allowDefinition="Everywhere" restartOnExternalChanges="false" allowExeDefinition="MachineToApplication"/>        </sectionGroup> 
-->

<!-- 
<fiftyOne>        
	<wurfl wurflFilePath="~/App_Data/wurfl.xml.gz">            
		<wurflPatches>                
			<add name="browser_definitions" filePath="~/App_Data/web_browsers_patch.xml" enabled="true"/>            
		</wurflPatches>        
	</wurfl>    
</fiftyOne> 
-->

Commenting out these sections in web.config will disable the Mobile Foundation module from loading and interfering with the Sitefinity Login page. I hope to resolve this soon with the help of 51 Degrees, makers of the Mobile Foundation.

Overview

I think by far the best part of Sitefinity is how it is built on and makes full use of the ASP.NET architecture. Because of things like Code-Behind, Themes, Skins, and other foundations of the Framework, Sitefinity is more open and extensible than any other CMS platform I've ever used.

A direct consequence of the separation of content vs design is how easy it is to "swtich themes". It's as simple as populating a new Theme folder with new css and images mapped to the css classes defined in your page. It was a simple matter to take this one step further by creating a "Mobile" theme that can be switched to automatically based on the capabilities of the device accessing the site!

Detecting the device was the hard part. I experimented with many options including using the wurfl asp.net API, and then when that didn't work, even building my own wurfl wrapper. Not having the time nor patience to dive into that can of worms, I was relieved to discover that an excellent mobile kit had already been developed by 51 Degrees. Their Mobile Toolkit is a GODSEND; easy to install, configure, and use! If you have ANY mobile device needs for your website, start with 51 Degrees!

Installation and Setup

The Sitefinity Toolkit already includes the necessary Mobile Toolkit libraries to run this feature, but make sure you download the correct version for your Sitefinity installation and unzip to your site's bin folder.

In order for detection to work, you must make sure to download the latest WURFL definitions and patch file and place them somewhere accessible on your site (I placed mine in the App_Data folder). Map the files in your web.config, as well as some additional settings by adding the following to your config file (note the file locations):

<?xml version="1.0" encoding="UTF-8"?>
<configuration>    
    <configSections>        
        <sectionGroup name="mobile">            
            <section name="toolkit" type="Mobile.Configuration.ToolkitSection, Mobile, Version=0.1.5.0, Culture=neutral" allowDefinition="Everywhere" restartOnExternalChanges="false" allowExeDefinition="MachineToApplication"/>            
            <section name="wurfl" type="Mobile.Devices.Wurfl.Configuration.WurflSection, Mobile, Version=0.1.5.0, Culture=neutral" allowDefinition="Everywhere" restartOnExternalChanges="false" allowExeDefinition="MachineToApplication"/>        
        </sectionGroup>    
    </configSections> 
    
    ...

    <mobile>        
        <toolkit logFile="~/App_Data/MobileLog.txt" logLevel="warn"/>        
        <wurfl wurflFilePath="~/App_Data/wurfl.xml.gz">            
            <wurflPatches>                
                <add name="browser_definitions" filePath="~/App_Data/web_browsers_patch.xml" enabled="true"/>            
            </wurflPatches>        
        </wurfl>    
    </mobile>
</configuration>

NOTE: For detailed instructions on how to customize this configuration, please take a look at the .NET Mobile API User Guide from the 51 Degrees website.

Normally to use the toolkit, you would add their Detector HttpModule to your web.config. However, since this is running in Sitefinity, there's a few extra steps I wanted to go through after detecting the device to store the status in session. This way, you don't have to check the device on every session. Also, if a mobile user wants to see the full site, or vice-versa, you can save that in the session as well, bypassing the check (more on how to do that later).

To do this, I inherited from the default Detector module and made my own, so that's the one you should add to your web.config HttpModules nodes:

For IIS 6

<system.web>    
    <httpModules>        
        <add name="BrowserDetector" type="SelArom.Net.Sitefinity.HttpModules.BrowserDetectModule" />    
    </httpModules>
</system.web>

For IIS 7

<system.webServer>    
    <modules>        
        <add name="BrowserDetector" type="SelArom.Net.Sitefinity.HttpModules.BrowserDetectModule" preCondition="managedHandler" />    
    </modules>
</system.webServer>

Detecting Page

Since all page requests in Sitefinity are internally routed through a single entry point (located at /Sitefinity/cmsentrypoint.aspx), you need to modify this page to inherit from the Toolkit Detector Page. This internal page handles all the fenagling to switch the to your mobile theme and master page (see next section below for requirements).

All you have to do is change the base class from which this entry point page inherits:

<%@ Page Inherits="SelArom.Net.Sitefinity.Pages.DetectingPage" MasterPageFile="~/Sitefinity/Dummy.master" %>

Mobile Theme Requirements

When a mobile device is detected (or the mobile view is forced, explained later), the Detecting Page above automatically switches to the "Mobile" theme and switches the underlying MasterPage to "Mobile.Master". In order for this to work without crashing, you MUST have an ASP.NET Theme Folder named "Mobile" and it MUST be called "Mobile". In addition, you MUST also define a "Mobile.Master" file in your App_Master folder (which MUST also exist). These are the files used by the Detector to switch themes.

In future releases I hope to be able to allow you to choose the themes and master pages, but for now, you can style and define these however you wish to best suit your website. However they MUST match these file names and MUST live in the specified folders.

For help getting started with a mobile theme, be sure and check out the Sitefinity Mobile Starter Theme available in the Sitefinity Marketplace. It is an awesome starter theme developed by the kind folks at Data Universal Inc.

Usage and Examples

After configuring everything above, your website should now automatically detect mobile devices and switch themes. Try visiting any of these sites from a mobile device (or click the Mobile link to preview the mobile version on your PC); all of them use the Sitefinity Toolkit:

• City of McAllen (Mobile)
• McAllen Library - (Mobile)
• Quinta Mazatlan - (Mobile)

If you compare these to the full desktop versions, you'll see that the text, links, pictures, and other content are pretty much exactly the same! This is because other than a few customizations here and there, it IS the same content. With this toolkit (and associated theme/master page) you don't have to make a separate mobile site; you can feed the same content to ALL your users!

Switching Modes

Notice how both versions of these sites have a link for you to switch between mobile and full versions of the site. As you may have guessed from the links above, the "mobile" query string is used to switch between modes. Adding "?mobile=1" to the full site will switch to mobile, and it will KEEP that selection through all future pages until you either switch back or your session expires!

Switching back is simply a matter of appending the querystring to the current Url. You can place this link anywhere (I recommend on the header of your master page). Here is the code I use to create the link on the main page to swtich to mobile view (first define a HyperLink control called lnkMobile):

protected override void OnInit(EventArgs e)
{
    base.OnInit(e);

    var url = Request.RawUrl.ToLower();
    if (url.Contains("mobile="))
        url = url.Replace("mobile=0", "mobile=1");
    else if (url.Contains("?"))
        url = string.Concat(url, "&mobile=1");
    else url = string.Concat(url, "?mobile=1");

    lnkMobile.NavigateUrl = url;
}

To switch back, simply reverse the polarity of the mobile flag (Add this to your Mobile.Master page):

var url = Request.Url.ToString().ToLower();
if (url.Contains("mobile="))
    url = url.Replace("mobile=1", "mobile=0");
else    if (url.Contains("?"))
        url = string.Concat(url, "&mobile=0");
    else url = string.Concat(url, "?mobile=0");

lnkFull.NavigateUrl = url;

In a much later release I hope to include a "SwitchModeLink" control that you can drop onto a page, but for now, the code above should work just fine.

Tookit Version 1.1

I've discovered a few bugs and issues in the 1.0 release of the toolkit, and I'll be creating a separate post to go over the details. However, there is one change to this particular feature I'd like to quickly cover.

In 1.0, the querystring remained appended to the url, causing double indexing in google to the same page. Since these are technically the same page, they should only have one Url.

So for 1.1 I've modified the code so that when you switch modes with the Querystring, the Detector HttpModule will automatically 301 redirect that Url to the correct Url that does NOT have that mobile flag in it. That way when your pages are crawled, only the original url to your page is ever indexed.

I hope to publish 1.1 before the end of the week. If you need it RIGHT AWAY (such as if you're experiencing some bugs) lease email me and I'll send you a link to download it. Those requests accompanied by a kind donation (see sidebar for details) will get a priority response, but of course no donation is ever required to access my work (though it's always appreciated)!

If I left anything out, please let me know, and as always your comments and suggestions are welcome.

Toolkit Version 1.2

The Module will now no longer crash if the Mobile theme and Master Page are not present. Instead, the Module will create the empty theme and assign it, using the default Master Page in place. This should create a clean, mostly empty style that should render well on mobile devices.

There are some other improvements and tweaks, but make sure you take note of the very important issue noted at the top of this blog post. I will release a fix as soon as I get one worked out.