├── mobility
    ├── __init__.py
    ├── middleware.py
    ├── decorators.py
    └── tests.py
├── .gitignore
├── MANIFEST.in
├── runtests.sh
├── setup.py
├── LICENSE
└── README.rst


/mobility/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.py[co]
2 | *.sw[po]
3 | *~
4 | 


--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include LICENSE
2 | include README.rst
3 | 


--------------------------------------------------------------------------------
/runtests.sh:
--------------------------------------------------------------------------------
 1 | #!/bin/sh
 2 | 
 3 | SETTINGS='settings.py'
 4 | 
 5 | cat > $SETTINGS <<EOF
 6 | DATABASES = {
 7 |     'default': {
 8 |             'ENGINE': 'django.db.backends.sqlite3'
 9 |     },
10 | }
11 | EOF
12 | 
13 | export DJANGO_SETTINGS_MODULE=settings
14 | 
15 | python -m unittest discover
16 | 
17 | rm -f $SETTINGS
18 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | import os
 2 | from setuptools import setup, find_packages
 3 | 
 4 | ROOT = os.path.abspath(os.path.dirname(__file__))
 5 | 
 6 | 
 7 | setup(
 8 |     name='django-mobility',
 9 |     version='0.1',
10 |     description='Middleware and decorators for directing users to your mobile site.',
11 |     long_description=open(os.path.join(ROOT, 'README.rst')).read(),
12 |     author='Jeff Balogh',
13 |     author_email='jbalogh@mozilla.com',
14 |     url='http://github.com/jbalogh/django-mobility',
15 |     license='BSD',
16 |     packages=find_packages(),
17 |     include_package_data=True,
18 |     install_requires=['django'],
19 |     zip_safe=False,
20 |     classifiers=[
21 |         'Development Status :: 4 - Beta',
22 |         'Environment :: Web Environment',
23 |         'Environment :: Web Environment :: Mozilla',
24 |         'Framework :: Django',
25 |         'Intended Audience :: Developers',
26 |         'License :: OSI Approved :: BSD License',
27 |         'Operating System :: OS Independent',
28 |         'Programming Language :: Python',
29 |         'Topic :: Software Development :: Libraries :: Python Modules',
30 |     ]
31 | )
32 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2011, Mozilla Foundation.
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without modification,
 5 | are permitted provided that the following conditions are met:
 6 | 
 7 |     1. Redistributions of source code must retain the above copyright notice,
 8 |        this list of conditions and the following disclaimer.
 9 | 
10 |     2. Redistributions in binary form must reproduce the above copyright
11 |        notice, this list of conditions and the following disclaimer in the
12 |        documentation and/or other materials provided with the distribution.
13 | 
14 |     3. Neither the name of django-mobility nor the names of its contributors
15 |        may be used to endorse or promote products derived from this software
16 |        without specific prior written permission.
17 | 
18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
22 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
25 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 | 


--------------------------------------------------------------------------------
/mobility/middleware.py:
--------------------------------------------------------------------------------
 1 | import re
 2 | 
 3 | from django.conf import settings
 4 | from django.http import HttpResponsePermanentRedirect
 5 | from django.utils.cache import patch_vary_headers
 6 | 
 7 | 
 8 | # Mobile user agents.
 9 | USER_AGENTS = 'android|fennec|iemobile|iphone|opera (?:mini|mobi)'
10 | USER_AGENTS = re.compile(getattr(settings, 'MOBILE_USER_AGENTS', USER_AGENTS))
11 | 
12 | # We set a cookie if you explicitly select mobile/no mobile.
13 | COOKIE = getattr(settings, 'MOBILE_COOKIE', 'mobile')
14 | 
15 | 
16 | # We do this in zeus for performance, so this exists for the devserver and
17 | # to work out the logic.
18 | class DetectMobileMiddleware(object):
19 | 
20 |     def process_request(self, request):
21 |         ua = request.META.get('HTTP_USER_AGENT', '').lower()
22 |         mc = request.COOKIES.get(COOKIE)
23 |         if (USER_AGENTS.search(ua) and mc != 'off') or mc == 'on':
24 |             request.META['HTTP_X_MOBILE'] = '1'
25 | 
26 |     def process_response(self, request, response):
27 |         if not getattr(request, 'NO_MOBILE', False):
28 |             patch_vary_headers(response, ['User-Agent'])
29 |         return response
30 | 
31 | 
32 | class XMobileMiddleware(object):
33 | 
34 |     def redirect(self, request, base):
35 |         path = base.rstrip('/') + request.path
36 |         if request.GET:
37 |             path += '?' + request.GET.urlencode()
38 |         response = HttpResponsePermanentRedirect(path)
39 |         response['Vary'] = 'X-Mobile'
40 |         return response
41 | 
42 |     def process_request(self, request):
43 |         try:
44 |             want_mobile = int(request.META.get('HTTP_X_MOBILE', 0))
45 |         except Exception:
46 |             want_mobile = False
47 |         request.MOBILE = want_mobile
48 | 
49 |     def process_response(self, request, response):
50 |         if not getattr(request, 'NO_MOBILE', False):
51 |             patch_vary_headers(response, ['X-Mobile'])
52 |         return response
53 | 


--------------------------------------------------------------------------------
/mobility/decorators.py:
--------------------------------------------------------------------------------
 1 | import functools
 2 | 
 3 | 
 4 | def mobile_template(template):
 5 |     """
 6 |     Mark a function as mobile-ready and pass a mobile template if MOBILE.
 7 | 
 8 |     @mobile_template('a/{mobile/}/b.html')
 9 |     def view(request, template=None):
10 |         ...
11 | 
12 |     if request.MOBILE=True the template will be 'a/mobile/b.html'.
13 |     if request.MOBILE=False the template will be 'a/b.html'.
14 | 
15 |     This function is useful if the mobile view uses the same context but a
16 |     different template.
17 |     """
18 |     def decorator(f):
19 |         @functools.wraps(f)
20 |         def wrapper(request, *args, **kw):
21 |             fmt = {'mobile/': 'mobile/' if request.MOBILE else ''}
22 |             kw['template'] = template.format(**fmt)
23 |             return f(request, *args, **kw)
24 |         return wrapper
25 |     return decorator
26 | 
27 | 
28 | def mobilized(normal_fn):
29 |     """
30 |     Replace a view function with a normal and mobile view.
31 | 
32 |     def view(request):
33 |         ...
34 | 
35 |     @mobilized(view)
36 |     def view(request):
37 |         ...
38 | 
39 |     The second function is the mobile version of view. The original
40 |     function is overwritten, and the decorator will choose the correct
41 |     function based on request.MOBILE (set in middleware).
42 |     """
43 |     def decorator(mobile_fn):
44 |         @functools.wraps(mobile_fn)
45 |         def wrapper(request, *args, **kw):
46 |             if request.MOBILE:
47 |                 return mobile_fn(request, *args, **kw)
48 |             else:
49 |                 return normal_fn(request, *args, **kw)
50 |         return wrapper
51 |     return decorator
52 | 
53 | 
54 | def not_mobilized(f):
55 |     """
56 |     Explicitly mark this function as not mobilized. If marked,
57 |     Vary headers will not be sent.
58 |     """
59 |     @functools.wraps(f)
60 |     def wrapper(request, *args, **kw):
61 |         request.NO_MOBILE = True
62 |         return f(request, *args, **kw)
63 |     return wrapper
64 | 


--------------------------------------------------------------------------------
/README.rst:
--------------------------------------------------------------------------------
  1 | What is this?
  2 | -------------
  3 | 
  4 | This library is a collection of middleware and decorators that help in creating
  5 | mobile views and directing users to the mobile version of your site.  It makes
  6 | these assumptions:
  7 | 
  8 |  * You can use Vary: User-Agent to serve mobile and non-mobile content through
  9 |    the same URLs.
 10 |  * You want to use separate views and/or templates for the mobile site. If
 11 |    you're building a mobile experience through media queries this library won't
 12 |    be helpful.
 13 |  * Not all views from the normal site need to be replaced with mobile views.
 14 | 
 15 | 
 16 | Support
 17 | -------
 18 | 
 19 | Written and tested on Django trunk with Python 2.6.
 20 | 
 21 | 
 22 | Setup
 23 | -----
 24 | 
 25 | These are the default settings::
 26 | 
 27 |     # A regex for detecting mobile user agents.
 28 |     MOBILE_USER_AGENTS = 'android|fennec|iemobile|iphone|opera (?:mini|mobi)'
 29 |     # The name of the cookie to set if the user prefers the mobile site.
 30 |     MOBILE_COOKIE = 'mobile'
 31 | 
 32 | You need these middleware (but see the User Agent caveats below)::
 33 | 
 34 |     MIDDLEWARE_CLASSES = (
 35 |         'mobility.middleware.DetectMobileMiddleware',
 36 |         'mobility.middleware.XMobileMiddleware',
 37 |     )
 38 | 
 39 | 
 40 | How the Mobile Site is Chosen
 41 | -----------------------------
 42 | 
 43 | 1. The ``HTTP_USER_AGENT`` matches ``MOBILE_USER_AGENTS`` and the
 44 |    ``MOBILE_COOKIE`` is not set to ``off``.
 45 | 2. *or* the ``MOBILE_COOKIE`` is set to ``on``.
 46 | 3. A mobile view exists for the current URL.
 47 | 
 48 | The ``HTTP_USER_AGENT`` is checked against the regular expression in
 49 | ``MOBILE_USER_AGENTS``. The default is a very basic set of user agents to ease
 50 | maintenance and because the cookie provides a fallback.
 51 | 
 52 | If ``MOBILE_COOKIE`` is set to ``on``, through ``Set-Cookie`` or through
 53 | javascript, the mobile site will be chosen regardless of the user agent. If
 54 | ``MOBILE_COOKIE`` is set to ``off`` the normal site will always be chosen.
 55 | 
 56 | 
 57 | Changes to the ``request`` Object
 58 | ---------------------------------
 59 | 
 60 | If the current request is for the mobile site, ``request.MOBILE = True``. At
 61 | all other times ``request.MOBILE = False``.
 62 | 
 63 | 
 64 | Decorators
 65 | ----------
 66 | 
 67 | Some decorators are provided to assist with common idioms::
 68 | 
 69 |     @mobile_template('app/{mobile/}detail.html')
 70 |     def view(request, template=None):
 71 |         ...
 72 | 
 73 | ``@mobile_template`` helps with the pattern of using the same view code and
 74 | template context, but switching to a different template for mobile. It follows
 75 | this logic::
 76 | 
 77 |     template = 'app/mobile/detail.html' if request.MOBILE else 'app/detail.html'
 78 | 
 79 | To use a completely different function for the mobile view::
 80 | 
 81 |     def view(request):
 82 |         ...
 83 | 
 84 |     @mobilized(view)
 85 |     def view(request):
 86 |         ...
 87 | 
 88 | In the example, the first definition of ``view`` will be used for the normal
 89 | site and the second function will be used for the mobile site. The normal and
 90 | mobile site point to the same view in ``urls.py`` and the decorator handles
 91 | choosing which view to run.
 92 | 
 93 | 
 94 | Varying on User Agent
 95 | ---------------------
 96 | 
 97 | Since mobile users can enter the site from any normal URL, the
 98 | ``DetectMobileMiddleware`` always inspects the ``User-Agent`` to see if it
 99 | matches something in ``MOBILE_USER_AGENTS``, and may redirect the browser to
100 | the mobile site. Thus, every URL on the site should be sending ``Vary:
101 | User-Agent`` to get proper HTTP caching. Varying on User-Agent can be
102 | detrimental to your frontend cache scheme, so it's recommended that you move
103 | mobile detection up the stack to a frontend proxy.
104 | 
105 | The proxy can run the logic in ``DetectMobileMiddleware`` and set
106 | ``HTTP_X_MOBILE`` (so we know whether to serve a mobile view) without varying
107 | on user agent internally. Instead, it can vary on ``X-Mobile`` while
108 | sending ``Vary: User-Agent`` back to the client. From the outside it looks like
109 | the app varies on ``User-Agent`` but the proxy will only need to cache a
110 | mobile and non-mobile version of the URL.
111 | 


--------------------------------------------------------------------------------
/mobility/tests.py:
--------------------------------------------------------------------------------
  1 | # -*- coding: utf-8 -*-
  2 | import unittest
  3 | 
  4 | from django import http, test
  5 | from django.utils import http as urllib
  6 | 
  7 | from mobility import decorators, middleware
  8 | 
  9 | 
 10 | FENNEC = ('Mozilla/5.0 (Android; Linux armv7l; rv:2.0b8) '
 11 |           'Gecko/20101221 Firefox/4.0b8 Fennec/4.0b3')
 12 | FIREFOX = 'Mozilla/5.0 (Windows NT 5.1; rv:2.0b9) Gecko/20100101 Firefox/4.0b9'
 13 | 
 14 | 
 15 | class TestDetectMobile(unittest.TestCase):
 16 | 
 17 |     def check(self, mobile, ua=None, cookie=None):
 18 |         d = {}
 19 |         if cookie:
 20 |             d['HTTP_COOKIE'] = 'mobile=%s' % cookie
 21 |         if ua:
 22 |             d['HTTP_USER_AGENT'] = ua
 23 |         request = test.RequestFactory().get('/', **d)
 24 |         response = middleware.DetectMobileMiddleware().process_request(request)
 25 |         assert response is None
 26 |         if mobile:
 27 |             self.assertEqual(request.META['HTTP_X_MOBILE'], '1')
 28 |         else:
 29 |             assert 'HTTP_X_MOBILE' not in request.META
 30 | 
 31 |     def test_mobile_ua(self):
 32 |         self.check(mobile=True, ua=FENNEC)
 33 | 
 34 |     def test_mobile_ua_and_cookie_on(self):
 35 |         self.check(mobile=True, ua=FENNEC, cookie='on')
 36 | 
 37 |     def test_mobile_ua_and_cookie_off(self):
 38 |         self.check(mobile=False, ua=FENNEC, cookie='off')
 39 | 
 40 |     def test_nonmobile_ua(self):
 41 |         self.check(mobile=False, ua=FIREFOX)
 42 | 
 43 |     def test_nonmobile_ua_and_cookie_on(self):
 44 |         self.check(mobile=True, ua=FIREFOX, cookie='on')
 45 | 
 46 |     def test_nonmobile_ua_and_cookie_off(self):
 47 |         self.check(mobile=False, ua=FIREFOX, cookie='off')
 48 | 
 49 |     def test_no_ua(self):
 50 |         self.check(mobile=False)
 51 | 
 52 |     def test_vary(self):
 53 |         request = test.RequestFactory().get('/')
 54 |         response = http.HttpResponse()
 55 |         r = middleware.DetectMobileMiddleware().process_response(request,
 56 |                                                                  response)
 57 |         assert r is response
 58 |         self.assertEqual(response['Vary'], 'User-Agent')
 59 | 
 60 | 
 61 | class TestXMobile(unittest.TestCase):
 62 | 
 63 |     def check(self, xmobile, mobile):
 64 |         request = test.RequestFactory().get('/')
 65 |         if xmobile:
 66 |             request.META['HTTP_X_MOBILE'] = xmobile
 67 |         middleware.XMobileMiddleware().process_request(request)
 68 |         self.assertEqual(request.MOBILE, mobile)
 69 | 
 70 |     def test_bad_xmobile(self):
 71 |         self.check(xmobile='xxx', mobile=False)
 72 | 
 73 |     def test_no_xmobile(self):
 74 |         self.check(xmobile=None, mobile=False)
 75 | 
 76 |     def test_xmobile_1(self):
 77 |         self.check(xmobile='1', mobile=True)
 78 | 
 79 |     def test_xmobile_0(self):
 80 |         self.check(xmobile='0', mobile=False)
 81 | 
 82 |     def test_vary(self):
 83 |         request = test.RequestFactory().get('/')
 84 |         response = http.HttpResponse()
 85 |         r = middleware.XMobileMiddleware().process_response(request, response)
 86 |         assert r is response
 87 |         self.assertEqual(response['Vary'], 'X-Mobile')
 88 | 
 89 |         response['Vary'] = 'User-Agent'
 90 |         middleware.XMobileMiddleware().process_response(request, response)
 91 |         self.assertEqual(response['Vary'], 'User-Agent, X-Mobile')
 92 | 
 93 | 
 94 | class TestMobilized(unittest.TestCase):
 95 | 
 96 |     def setUp(self):
 97 |         normal = lambda r: 'normal'
 98 |         mobile = lambda r: 'mobile'
 99 |         self.view = decorators.mobilized(normal)(mobile)
100 |         self.request = test.RequestFactory().get('/')
101 | 
102 |     def test_call_normal(self):
103 |         self.request.MOBILE = False
104 |         self.assertEqual(self.view(self.request), 'normal')
105 | 
106 |     def test_call_mobile(self):
107 |         self.request.MOBILE = True
108 |         self.assertEqual(self.view(self.request), 'mobile')
109 | 
110 | 
111 | class TestNotMobilized(unittest.TestCase):
112 | 
113 |     def setUp(self):
114 |         self.view = lambda r: getattr(r, 'NO_MOBILE', False)
115 |         self.request = test.RequestFactory().get('/')
116 | 
117 |     def test_call_normal(self):
118 |         self.assertEqual(self.view(self.request), False)
119 | 
120 |     def test_call_nonmobile(self):
121 |         view = decorators.not_mobilized(self.view)
122 |         self.assertEqual(view(self.request), True)
123 | 
124 |     def test_vary_xmobile(self):
125 |         request = test.RequestFactory().get('/')
126 |         request.NO_MOBILE = True
127 |         response = http.HttpResponse()
128 | 
129 |         r = middleware.XMobileMiddleware().process_response(request, response)
130 |         self.assertEqual(response.get('Vary', None), None)
131 | 
132 |     def test_vary_detect_mobile(self):
133 |         request = test.RequestFactory().get('/')
134 |         request.NO_MOBILE = True
135 |         response = http.HttpResponse()
136 | 
137 |         r = middleware.DetectMobileMiddleware().process_response(request,
138 |                                                                  response)
139 |         self.assertEqual(response.get('Vary', None), None)
140 | 
141 | 
142 | class TestMobileTemplate(unittest.TestCase):
143 | 
144 |     def setUp(self):
145 |         template = 'a/{mobile/}b.html'
146 |         func = lambda request, template: template
147 |         self.view = decorators.mobile_template(template)(func)
148 |         self.request = test.RequestFactory().get('/')
149 | 
150 |     def test_normal_template(self):
151 |         self.request.MOBILE = False
152 |         self.assertEqual(self.view(self.request), 'a/b.html')
153 | 
154 |     def test_mobile_template(self):
155 |         self.request.MOBILE = True
156 |         self.assertEqual(self.view(self.request), 'a/mobile/b.html')
157 | 


--------------------------------------------------------------------------------