express-responsive

Introduction

Desktop devices are by far not the only devices a modern web developer has to expect today. We see it for granted to be able to view a website from our phones, tablets, or TV.

express-responsive extends the Express web framework of methods to respond to different devices appropriately.

Installation

npm install express-responsive

Usage

There are two ways of using express-responsive. You can attach middleware to your application and properly handle different devices explicitly to fit your needs, or you can use a more generic approach, and let Express search for proper templates itself.

Middleware approach

This example uses Jade as template engine. You can use whatever engine you like, as long as it follows the Express conventions.

var express = require('express'),
	responsive = require('responsive'),
	app = express();

app.configure(function() {
	app.set('views', __dirname + '/views');
	app.set('view engine', 'jade');

	// This is the important line!
	app.use(responsive.deviceCapture());
});

app.get('/', function(req, res) {
	if(req.device === 'phone') {
		res.render('phone');
	}
	else {
		res.render('index');
	}
});

Device dependent routing approach

Analogue to the middleware approach, we use the Jade engine as an example here.

var express = require('express'),
	responsive = require('responsive'),
	app = express();

app.configure(function() {
	app.set('views', __dirname + '/views');
	app.set('view engine', 'jade');

	// This is the important line!
	app.enableDeviceRouting();
});

app.get('/', function(req, res) {
	res.render('index');
});

When you call res.render, express-responsive will detect the device used, check if there is a template available for that device, and fallback otherwise.

For example, if you requested the website from your smartphone, res.render will first look if views/phone/index.jade exists. If it does it will render that view. If the file does not exist, it will fallback to views/index.jade.

Attention: Please note that req.device is not available when using this approach. If you want both device routing and req.device:

app.configure(function() {
	/* Your template engine here */

	app.use(responsive.deviceCapture());
	app.enableDeviceRouting();
});

Detected devices

express-responsive will divide devices into the categories

• desktop
• tablet
• phone
• tv
• bot

It will assume desktop if no user agent string is given, and fallback to phone if the user agent string is unknown.

Tests and documentation

express-responsive is written in CoffeeScript. When you have installed CoffeeScript globally and the development dependencies of express-responsive locally, you can just run from the main directory:

• cake test will run the test suites
• cake docs will generate documentation from source and store it in HTML format in the docs directory
• cake dist will build from source into the dist directory. Usually you do not need to execute this command - the lib directory holds compiled sources already!

Should you notice any device that is not properly detected, please be so kind to create an issue providing the user agent string of the device.

Purpose

This project is heavily based on express-device. Unfortunately, express-device is dependent on express-partials. This creates problems on many template engines (the most I tested so far besides EJS) due to known limitations within express-partials (see publicclass/express-partials#30).

License

express-responsive is licensed under the MIT license. For more information, please refer to the LICENSE.md file located in the main directory of the project.