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 suitescake docs
will generate documentation from source and store it in HTML format in thedocs
directorycake dist
will build from source into thedist
directory. Usually you do not need to execute this command - thelib
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.