Djangobile, Django Mobile Extension

Abstract

Djangobile is a django mobile extension for rendering web pages according to device capabilities. Therefore djangobile offers an implementation for W3C Working Draft IDEAL (Interface DEscription Authoring Language). Note: This software is under hard development.

Dependencies

Required

• PyWURFL (pywurfl-6.4.0b). A Python language package that makes dealing with the WURFL in Python a little easier. Special thanks for Armand Lynch for his patience.

Optional

• Levenshtein Module (python-Levenshtein-0.10.1). Required if you want to use the Levenshtein distance or Jaro-Winkler algorithms for user agent similarity.
• lxml (lxml-2.1beta3.tar.gz). Required in order to validate IDEAL XML templates against MyMobileWeb's IDEAL DTD scheme for presentations.
• pyparsing (pyparsing-1.5.1.tar.gz). Required if you want to use the PyWURFL query language for create devices families.

Instalation

Simply check out djangobile in a django project root.

svn checkout http://djangobile.googlecode.com/svn/trunk/djangobile djangobile

And set a new context processor in your project settings.py

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.core.context_processors.auth',
    'django.core.context_processors.debug',
    'django.core.context_processors.i18n',
    'django.core.context_processors.media',
    # This context processor is required to djangobile works properly.
    'djangobile.context_processors.mobile',

)

Options

Middleware

You can get device attribute in request object through a middleware.

MIDDLEWARE_CLASSES = (
    'django.middleware.common.CommonMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.middleware.doc.XViewMiddleware',
    # In order to use request.device in views.
    'djangobile.middleware.DjangoMobileMiddleware',
)

Application

Djangobile provides override_media_url and device_media_url in order to make easier to get media path according to device capabilities.

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',
    # In order to use override_media_url and device_media_url templatetag
    # in templates.
    'djangobile',
)

PyWURFL class

In order to provide your own WURFL class to djangobile, you must set WURFL_CLASS variable.

# Python WURFL class generated by wurfl2python.py script from pywurfl.
WURFL_CLASS = 'djangobile.wurfl'

User agent search algorithm

Djangobile can use three distinct search algorithm: Tokenizer (by default), Jaro Winkler or Levenshtein distance.

# Possible values are Tokenizer (default), JaroWinkler and LevenshteinDistance.
# JaroWinkler and LevenshteinDistance require Levenshtein Module >= 0.10.1.
USER_AGENT_SEARCH_ALGORITHM = 'Tokenizer'

For JaroWinkler search algorithm JARO_WINKLER_ACCURACY can be a value between 0 and 1. With values close to 1 you get a slower search.

# Accuracy value for JaroWinkler search algorithm (0 to 1).
# Default: 0.9
JARO_WINKLER_ACCURACY = 0.9

Capabilities search

In order to choose a template, djangobile uses a capabilities set to get the right template.

# List of device capabilities to order template search.
# Default: (id, user_agent, fall_back, preferred_markup, model_name, brand_name,
#           family)
DEVICE_SEARCH_ORDER = (
    'user_agent',
    'brand_name',
)

Devices definition

In order to define new devices, a file extra_devices.py can be created in the project root. The device definition uses PyWURFL syntax.

from djangobile import devices


devices.add(parent='generic',
            devid='fennec',
            devua='Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1b2pre) Gecko/20081015 Fennec/1.0a1',
            actual_device_root=True)

Devices families definition

One definition of family is a set of capabilities that aims to provide designated fine-grained control over the identification devices. In order to define new families, a file extra_families.py can be created in the project root. The device definition uses PyWURFL QueryLanguage (setting QUERY_LANGUAGE_SUPPORT to True in settings.py) or native Python (over Device object) syntax.

from djangobile import families


@families.add
def xhtml_mp_device(device):
    return (device.preferred_markup == 'html_wi_oma_xhtmlmp_1_0' or
            (device.preferred_markup == 'html_wi_w3_xhtmlbasic' and 
             device.html_wi_oma_xhtmlmp_1_0 == True))

# This syntax requires pyparsing module
families['morethan15columns_device'] = """columns >= 15"""

Obviously, the Python syntax is incredibly faster.

Prefix of loader tags

Djangobile provides two loader tags which are automatically added in order to make easier to write templates: those are "extends" and "include" templatetags device aware. This settings allows to define the prefix for them. By default its value is 'device', being the templatetags "device_extends" and "device_include". But if it's None , the native templatetags will be overwritten with those where suitable.

# Prefix for "extends" and "includes" templatetags device aware.
# If None, the native templatetags will be overwritten with
# those where suitable.
# Default: device.
# And its use in templates is such as {% device_extends "template.hmtl" %}
DEVICE_LOADER_TAGS_PREFIX = 'device'

Prefix of device_media_url tag

By default its value is 'device', being the templatetag "device_media_url". # Prefix for media_url templatetag device aware. # If None, the templatetags is named media_url # Default: device. # And its use in templates is such as {% device_media_url "css/style.css" %}

DEVICE_MEDIA_URL_TAG_PREFIX = None

Show device log

In order to show detected device information in standard ouput, you can use this setting.

# If you set this to True, djangobile will print information about device in
# each request through standard output. Useful to debug issues.
# Default: True
DEVICE_SHOW_LOG = True