django-mobile 0.7.0

Changing the current flavour

The basic use case of django-mobile is obviously to serve a mobile version of your site to users. The selection of the correct flavour is usually already done in the middlewares when your own views are called. In some cases you want to change the currently used flavour in your view or somewhere else. You can do this by simply calling django_mobile.set_flavour(flavour[, permanent=True]). The first argument is self explaining. But keep in mind that you only can pass in a flavour that you is also in your FLAVOURS setting. Otherwise set_flavour will raise a ValueError. The optional permanent parameters defines if the change of the flavour is remember for future requests of the same client.

Your users can set their desired flavour them self. They just need to specify the flavour GET parameter on a request to your site. This will permanently choose this flavour as their preference to view the site.

You can use this GET parameter to let the user select from your available flavours:

<ul>
    <li><a href="?flavour=full">Get the full experience</a>
    <li><a href="?flavour=mobile">View our mobile version</a>
    <li><a href="?flavour=ipad">View our iPad version</a>
</ul>

Notes on caching

Django is shipping with some convenience methods to easily cache your views. One of them is django.views.decorators.cache.cache_page. The problem with caching a whole page in conjunction with django-mobile is, that django’s caching system is not aware of flavours. This means that if the first request to a page is served with a mobile flavour, the second request might also get a page rendered with the mobile flavour from the cache – even if the second one was requested by a desktop browser.

django-mobile is shipping with it’s own implementation of cache_page to resolve this issue. Please use django_mobile.cache.cache_page instead of django’s own cache_page decorator.

You can also use django’s caching middlewares django.middleware.cache.UpdateCacheMiddleware and FetchFromCacheMiddleware like you already do. But to make them aware of flavours, you need to add django_mobile.cache.middleware.FetchFromCacheFlavourMiddleware item before standard Django FetchFromCacheMiddleware in the MIDDLEWARE_CLASSES settings and django_mobile.cache.middleware.UpdateCacheFlavourMiddleware before django_mobile.cache.middleware.UpdateCacheMiddleware correspondingly.

It is necessary to split the usage of CacheMiddleware because some additional work should be done on request and response before standard caching behavior and that is not possible while using two complete middlewares in either order

MobileDetectionMiddleware

The built-in middleware to detect if the user is using a mobile browser served well in production but is far from perfect and also implemented in a very simplistic way. You can safely remove this middleware from your settings and add your own version instead. Just make sure that it calls django_mobile.set_flavour at some point to set the correct flavour for you.

Settings

Here is a list of settings that are used by django-mobile and can be changed in your own settings.py:

FLAVOURS

A list of available flavours for your site.

Default: ('full', 'mobile')

DEFAULT_MOBILE_FLAVOUR

The flavour which is chosen if the built-in MobileDetectionMiddleware detects a mobile browser.

Default: 'mobile'

FLAVOURS_COOKIE_HTTPONLY

The value that get passed into HttpResponse.set_cookie’s httponly argument. Set this to True if you don’t want the Javascript code to be able to read the flavour cookie.

Default: False

FLAVOURS_COOKIE_KEY

The cookie name that is used for storing the selected flavour in the browser. This is only used if FLAVOURS_STORAGE_BACKEND is set to 'cookie'.

Default: 'flavour'

FLAVOURS_TEMPLATE_PREFIX

This string will be prefixed to the template names when searching for flavoured templates. This is useful if you have many flavours and want to store them in a common subdirectory. Example:

from django.template.loader import render_to_string
from django_mobile import set_flavour

set_flavour('mobile')
render_to_string('index.html') # will render 'mobile/index.html'

# now add this to settings.py
FLAVOURS_TEMPLATE_PREFIX = 'flavours/'

# and try again

set_flavour('mobile')
render_to_string('index.html') # will render 'flavours/mobile/index.html'

Default: '' (empty string)

FLAVOURS_TEMPLATE_LOADERS

django-mobile’s template loader can load templates prefixed with the current flavour. Specify with this setting which loaders are used to load flavoured templates.

Default: same as TEMPLATE_LOADERS setting but without 'django_mobile.loader.Loader'.

FLAVOURS_GET_PARAMETER

Users can change the flavour they want to look at with a HTTP GET parameter. This determines the name of this parameter. Set it to None to disable.

Default: 'flavour'

FLAVOURS_SESSION_KEY

The user’s preference set with the GET parameter is stored in the user’s session. This setting determines which session key is used to hold this information.

Default: 'flavour'

FLAVOURS_STORAGE_BACKEND

Determines how the selected flavour is stored persistently. Available values: 'session' and 'cookie'.

Default: 'cookie'

Cache Settings

Django ships with the cached template loader django.template.loaders.cached.Loader that doesn’t require to fetch the template from disk every time you want to render it. However it isn’t aware of django-mobile’s flavours. For this purpose you can use 'django_mobile.loader.CachedLoader' as a drop-in replacement that does exactly the same django’s version but takes the different flavours into account. To use it, put the following bit into your settings.py file:

TEMPLATE_LOADERS = (
    ('django_mobile.loader.CachedLoader', (
          'django_mobile.loader.Loader',
          'django.template.loaders.filesystem.Loader',
          'django.template.loaders.app_directories.Loader',
    )),
)

0.7.0

• #64: Fixing cache_page decorator and splitting the CacheFlavourMiddleware into two middlewares. This follows the same strategy as Django did since quite a while. Please see #64 for more details about why this is necessary.

  If you are using CacheFlavourMiddleware, you need to replace it now with FetchFromCacheFlavourMiddleware and UpdateCacheMiddleware. Please consolidate the README for more information.

  Thanks to Yury Paykov for the patch.

0.6.0

• #63: Django 1.9 support. Thanks to Alexandre Vicenzi for the patch.

0.5.1

• #58: Fix Python 3 install issues related to unicode strings. Thanks to Zowie for inspiring the patch.

0.5.0

• Support for Django 1.7 and Django 1.8. Thanks to Jose Ignacio Galarza and to Anton Shurashov for the patches.

0.4.0

• Python 3.3 compatibility, thanks Mirko Rossini for the patch.

• Dropping Django 1.3 and 1.4 support.

0.3.0

• Dropping support for python 2.5 (it might still work but we won’t test against it anymore).

• Fixing threading problems because of wrong usage of threading.local. Thanks to Mike Shultz for the patch.

• Adding a cached template loader. Thanks to Saverio for the patch.

0.2.4

• FIX: Cookie backend actually never really worked. Thanks to demidov91 for the report.

0.2.3

• FIX: set flavour in all cases, not only if a mobile browser is detected. Thanks to John P. Kiffmeyer for the report.

0.2.2

• FIX: Opera Mobile on Android was categorized as mobile browser. Thanks to dgerzo for the report.

• Sniffing for iPad so that it doesn’t get recognized as small mobile device. Thanks to Ryan Showalter for the patch.

0.2.1

• Fixed packing issues that didn’t include the django_mobile.cache package. Thanks to Scott Turnbull for the report.

0.2.0

• Restructured project layout to remove settings.py and manage.py from top-level directory. This resolves module-name conflicts when installing with pip’s -e option. Thanks to bendavis78 for the report.

• Added a cache_page decorator that emulates django’s cache_page but takes flavours into account. The caching system would otherwise cache the flavour that is currently active when a cache miss occurs. Thanks to itmustbejj for the report.

• Added a CacheFlavourMiddleware that makes django’s caching middlewares aware of flavours. We use interally the Vary response header and the X-Flavour request header.

0.1.4

• Fixed issue in template loader that only implemented load_template_source but no load_template. Thanks to tylanpince, rwilcox and Frédéric Roland for the report.

0.1.3

• Fixed issue with runserver command that didn’t handled all request independed from each other. Thanks to bclermont and Frédéric Roland for the report.

0.1.2

• Fixed unreferenced variable error in SetFlavourMiddleware.

0.1.1

• Fixed is_usable attribute for django_mobile.loader.Loader. Thanks Michela Ledwidge for the report.

0.1.0

• Initial release.