webadmin's picture

Drupal How To Make your site mobile with Mobile Tools


This page contains the documentation for the Mobile Tools module.

The Mobile Tools module is your companion in providing a mobile experience with your Drupal site. The module is targeted both towards making a mobile version of your existing Drupal site, and making a mobile site from scratch.

The general idea of the module is to help Drupal developers in numerous ways to mobilize their website and provide a range of tools.

Making a mobile website is not only changing the theme, removing images or css else but involves a range of steps pre-processing your site. Following steps are important in the mobilization process:

1. Redirect mobile users to your mobile website (make sure your mobile site gets visitors!)
2. Decide which content is visible to the mobile users, and what actions can be done by them. This is needed in order to not overload your mobile site with non-relevant content and functionality. To much content and functinoality will lead to confusion, and always results in complex and difficult navigation.
3. Switch themes, or configure the layout for your mobile site: you can provide special themes created for specific devices, or rearrange blocks of your desktop site.
4. Adapt your theme for optimal display on different kind of mobile devices. Adaptations means a lot of things: resizing images, reducing download size, cleanup of html and css that will not work on the visiting device, cleanup of javascript, minimizing download size, etc ... (Example of such an adaptation engine can be found on http://composer.siruna.com.

The Mobile Tools helps to accomplish the first three points in different ways.

So to summarize making a mobile website means:

1. Getting the mobile users to the right page
2. Make the relevant content available to mobile users
3. Make the relevant functionality available to mobile users
4. Adapt or choose your theme according to the visiting device (and there are many many more different devices then the iPhone and Android ;))

First things first, prerequisites for this module

Before starting to use this module you need to prepare your mobile site. This means are you going to setup a second site, re-use your drupal installation, use a transcoder, etc ...

Answering to the following questions can help out:

a. Do you want a seperate mobile url? If yes, continue with the questions. If not, this mean that you will be using the theme switching option of the module, that allows you to switch themes when a mobile user is visiting your device (and you can go on with the setup and configuration of the module). [this is the easiest solution]

b. Do you plan using a transcoder such as Siruna. Transcoders take your desktop site and mobilize this in some simpel steps. The transcoder provide you with a seperate url for your mobile site (or you can point your mobile domain name to the transcoder). If this is the case, check out the Siruna module, and continue configuring the module. [this is an advanced solution, giving best quality]

c. If you don't plan to use a transcoder, but have your own mobile domain name, then you have two extra options (let's say you own the domain: www.mysite.com):

c.1 The easiest way is to configure in your domain name configuration panel the domain m.mysite.com to point to your drupal installation. When this is the case, theme switching will only work if you disable cache on your drupal site!!.

c.2 The second way (but morecomplex), and the most performant way is to use a multi-site setup instead of using the theme switching. By using a multi-site setup, you will not have caching issues.[Advanced solution, the theme selection option is not relevant anymore]

When you have selected one of the above options, you can continue with the configuration of the module.
Setup and configuration of the module

In order to start using the module, go to the Mobile Tools project page and download the module. Untar the module in your all/sites/modules directory.

Go to the module configuration page (admin/build/modules) and enable the Mobile Tools module. When enabled, you will not see any changes to your site.
Step 1: get the mobile user to the right page

When a mobile user visits your site, there are different things you can do in order to bring the mobile user to the right page. The way you handle this is often a matter of personal taste and depends on the type of site you are creating.

In order to start using following methods, Enable the "Enable Redirection / notification" checkbox.

The Mobile Tools module provides following methods:
1. Do nothing, just provide a way that other modules know what type of device is visiting the site

This is not very useful and will probably not be used very often. It can be used for testing of making your own mobility module. In order to use this methode, enable the "Do nothing, just provide the $_SESSION['mobile_device'] variable" checkbox. The $_SESSION['mobile_device'] variable will contain an array describing the type of device (desktop or mobile) and if available, to which group the device belongs (e.g. Android, iPhone, Blackberry, ...).
If you are not developing, forget about this option.
2. Automatic redirection of mobile users to the mobile site

This is a more useful method. By enabling the "Automatic redirection to mobile or desktop site (requires a separate mobile and desktop url!)" checkbox, mobile users will be automatically redirected to your mobile site. (e.g. when a mobile user visits http://www.yoursite.com, the user will be redirected to http://m.yoursite.com).

In order to make this work, you have to give the url of your desktop site, and the url of your mobile site! It is advised to use conventions such a http://m.* or http://www.yoursite.mobi.

This method makes sure that your mobile users don't get stuck on your desktop site (because they don't see that there is a mobile version) and it minimizes the clicks the mobile users have to generate.

The module also allows definition of the theme that must be used for the mobile version, in case the mobile and desktop site are being served by the same Drupal installation. The theme that has to be used can be configured in the Mobile Tools theme configuration page.
3. Display a message to mobile users when visiting the desktop site

This third method is also a very often used method. This method displays a message to your mobile users when they are accessing your Desktop site. The message can contain a link to your mobile site, where the users can click on.

This allows users to better choose what version of the site they want to see on their device. In order to make this method work, you also have to provide the mobile url and the desktop url of your site!

This method also comes with some extra configurations:

* You can choose how many times the notification is shown, by providing the number of impressions: " value. 0 means always. This way you can remove the message if they user has been neglecting the message.
* The notification can be displayed as a block, or a message on top of the page. If you choose for "Message block", you have to go to the blocks configuration section (admin/build/block) and enable the "Mobile Tools block notification"-block. Now you can choose where the notification has to be displayed.
* You can provide a customized message by filling in the "To mobile users: " and "To desktop users: " textareas.

The notification works in two ways: when a desktop users visits your mobile site, he gets a message to go to the desktop site. When a mobile user visits the mobile site, he gets a message to got to the mobile site.

Again, the mobile site can be provided with another theme. See further.
4. Switch theme for a mobile user

Method 2 and 3 require you to enter a mobile url and a desktop url. If you don't have two urls, or you wish to provide just one url for both sites, you can do a simple theme switch.

If you enable "Switch the theme when a mobile user visits the site (only 1 url for both mobile and desktop url)." mobile users will get a mobile theme. See further on configuration of the mobile theme.

Further configuration will enable the selection of a mobile theme based on device group. This means that you can select a different theme for the iPhone, Blackberry, Android, etc...
Step 2: Defining the content that can be viewed and which functionality is available

The second step after you have redirected the mobile user to your mobile site, is the configuration of which functionality is available to the mobile user and what content the mobile user can see. The reason why this is important, it that you want to provide a lightweight experience to the mobile user. Providing too much options, or too much content can make the navigation and layout very difficult.

The mobile tools module helps you by creating mobile user roles.

In order to enable the usage of mobile user roles, enable "Activate mobile user roles" in the "Mobile roles" menu.
1. Mobile roles

A mobile roles is nothing more then a duplicate of one of the existing roles that will be assigned to the user, when he is accessing the site from a mobile device. Since most people will visit your mobile site as a anonymous user, the anonymous role will be the most important one. In the Drupal permissions panel you will see the duplicate roles, and you will be able to assign different permissions to the mobile version of the roles.

In order to activate the mobile roles, you can choose which existing roles must have a mobile counterpart. You can do this by selecting the checkboxes next to the available roles, and saving the configuration.

In the Drupal permissions system, you can configure the permissions for the mobile roles.
2. Supported modules

Mobile tools provides you a way to create mobile versions of each role. When a user visits your site, and if there is a mobile version of his role, this role get's automatically assigned to that user.

By having a mobile role for each user role, you can use your existing role based permission systems. Some examples:

* Content Access: define which content can be accessed by a mobile user.
* Node Access: define which content can be accessed by a mobile user.
* Node Privacy by Role
* Menu per role: Define which menu items can be seen by mobile users
* Frontpage: Define which frontpage must be used for the mobile user.
* ...

Mobile theme configuration

In the theme section page, options are available for switching themes. To use theme switching, enable the "Enable the mobile theme" checkbox.

Now, several options are available. You can choose a general theme that must be displayed for all mobile devices. You can further specify what themes should be used for different specific device groups (iphone, blackberry, android, ...).
Tip: reuse your desktop theme and make it mobile

Theme switching is very helpful if you have one or more mobile themes. However, when you don't want to rewrite your theme to be displayed on mobile devices, you can reuse your theme together with an adaptation engine (e.g. Siruna).

By following the next step, you can make optimal use of the transcoding engine:

* Go to your theme directory
* Create a new folder and give it a name (e.g. mobile-theme)
* Copy the contents of your current active theme into that folder
* rename the *.info file (e.g. if your active theme was Garland, rename to mobile-garland.info)
* Change the theme name into your new *.info file (e.g. name = Mobile Garland)
* Go to the theme configuration page and enable the new theme

Now your theme is available under a different name and you can assign different block configurations to the theme. In the Mobile Tools theme configuration page, you can choose y our new theme as your mobile theme.
You can simplify the layout as much as you want!!
Number of posts on the frontpage

As a small extra, the Mobile Tools module allows you to the number of nodes that are being displayed on the frontpage. This allow you to minimize the need for vertical scrolling for the end-user.
Using third party modules

The mobile tools module consist of two core algorithms that can be taken over by other modules:
Device Detection modules

If a module is able to detect if a visiting device is mobile, it can implements the hooks
hook_device_groups() and hook_is_mobile_device().

The hook_device_groups() returns a list of device groups the module can distinguish. The Mobile Tools module has the following implementation:
function mobile_tools_device_groups() {
return array('iphone', 'ipod', 'android', 'opera mini', 'blackberry');

the hook_is_mobile_device() must return an array of the form
array('type' => $type, 'group' => $group). $type can be mobile or desktop and $group must equal on of the elements returned by the hook_device_groups.

The reason for this hook is the presence of commercial providers of this information and the popularity of WURFL. Mobile Tools gives a basic implementation.
Site type detection

If 1 Drupal installation is used for both the mobile and the desktop site, there is a need for a mechanism to detect if the Drupal site is beeing mobilized or not. This is needed to decide if redirection is necessary, and allows mobile users to visit the desktop site.

The Mobile Tools module uses the url structure to detect if the site is being mobilized or not. Other modules like the Siruna module can also provide this information, if Siruna is being used to transcode your site.
Device capability detection (advanced usage for developers)

The Mobile Tools module currently doesn't provide information on the device characteristics such as screen size, browser capabilities, javascript support, etc ...
Different services exist that can provide this information (e.g. WURFL). In order to help developers to easily change provider of this information, the Mobile Tools module provides a generic interface to query device capability information.

In order to use this fuction you have to install at least one module with this capability. (e.g. WURFL).

device capabilities can be queried by calling:
mobile_tools_devicecapability($capability). Capability is a property of the device. For a list of properties, take a look at the WURFL documentation (http://wurfl.sourceforge.net/help_doc.php. )