Detects client features from javascript and exposes the information in the request/response cycle and templates contexts.

To get started using django-clientfeatures simply install it with pip:

$ pip install [email protected]:bpeschier/django-clientfeatures.git

Add "clientfeatures.apps.DeviceFeaturesAppConfig" to your project's INSTALLED_APPS setting ("clientfeatures" on Django 1.6) and "clientfeatures.middleware.DetectFeaturesMiddleware" to your MIDDLEWARE_CLASSES setting for the default detection. For template context support, add "clientfeatures.context_processors.client_features" to the list of CONTEXT_PREPROCESSORS.

clientfeatures is intended to identify what features are available on the client which are not always directly identifiable from HTTP headers: the screen density, size and which method of input is used. For this, it detects the features in javascript at the beginning of the session and stores it on a cookie.

A cookie is set with the devicePixelRatio, screen size and touch capabilities reported by the browser. This data is converted into a dictionary of features to be used within the request/response cycle.

The blatant downside is that all new sessions will have one extra (all be it very small) request with the accompanying round-trip time, which can be significant on mobile. The upside is that this overhead occurs only once and the resulting cookie can be used for varying the cache of the different responses. The served page is going to be the correct one for the device requesting it with no additional overhead (assuming you load specific assets for the client instead of general-purpose ones).

The detection page will distort normal referral information from the browser, and the detection javascript will save the original referrer for you.

The DetectFeaturesMiddleware adds a client_features dictionary to all request objects. By default it consists of the following items:

screen_density

Either default or retina.

screen_size

Either default or mobile.

input

Either pointer or touch.

When the template context preprocessor is configured, it wil expose the same dictionary as client_features.

The DetectFeaturesMiddleware is set-up to allow developers to hook in at any point of the detection, from naming the cookies and their expiration date to the actual detection and features dictionary exposed.

In such, the middleware acts a mechanism to detect new clients and figure out their capabilities so Django can adapt its response so it does not have to be done in the browser. One can easily add detection of new features, like which doctypes are supported, or adjust the screen size detection to have more fine-grained steps such as mobile, tablet, small_screen, large_screen and tv.

The job of detecting features on the client is done by the features/detect_javascript.html template, while the conversion into usable items is done by extract_features_from_detection in DetectFeaturesMiddleware.

The feature_tags template tag library overrides the default static template tag and accepts string format parameters for features in the client_features dictionary, for example:

{% static "css/screen-{input}.css" %}

This will result in css/screen-pointer.css for pointer-based devices like desktop computers and css/screen-touch.css for touch-based devices like tablets.

The feature_tags template tag library requires the context preprocessor to be added to your CONTEXT_PREPROCESSORS setting.

Devices without javascript will be diverted to the "default" setting, which is a normal pointer-operated client. This is done with a meta-refresh.

Crawlers and other clients can be exempted from the entire detection based on their User agent string. These clients will also be given the default profile, but will never see the detection page. These clients are defined in the featureless_agents property of the DetectFeaturesMiddleware.