Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A gem for building mobile optimized Rails applications using semantic, media query-based device detection and server side component optimization.
Ruby
tree: e3b8d93f25

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
vendor/assets/javascripts
.gitignore
.rvmrc
Gemfile
LICENSE.txt
README.md
Rakefile
ress.gemspec

README.md

Ress

A system for building mobile optimized Rails applications using semantic, media query-based device detection and server side progressive enhancement.

Background

Ress is an extension of the devicejs library written by Boris Smus. It adds a back end for adapting server responses based on client side feature detection. Ress allows you to specify alternate versions of your website, along with media queries for which devices should be redirected to which version.

How it Works

HTML Annotations

When you register alternate mobile versions of your website, Ress adds annotations to the <head> of your document that describe where these pages are located and which devices should be redirected to them.

For example, a typical alternate version for a mobile site might include a tag like this:

<link rel="alternate" media="only screen and (max-width: 640px)" href="http://m.example.com/page-1" >

The mobile version of the page would then have a link pointing back the canonical version:

<link rel="canonical" href="http://www.example.com/page-1" >

These annotations conform to SEO best practices for mobile optimized websites as documented by Google.

Feature Detection

When a request comes into your site, the javascript included with ress will parse all of the [rel="alternate"] links in your markup, and evalute their media queries to determine if there is an alternate version available that matches the client. If there is, the user is redirected to the url for that version.

Server Side Components

Ress allows you to customize how your Rails application responds to mobile requests in two ways:

  1. It adds controller and helper methods to detect which version of your site has been requested. This is useful for small tweeks in html or behaviour, eg:
<% if mobile_request? %>
  <%= image_tag 'low-res.png' %>
<% else %>
  <%= image_tag 'high-res.png' %>
<% end %>
  1. It prepends a view path for each alternate version of your site, so that you can override the templates or partials that are rendered for certain requests. For example if you want to render a different html form for creating users on the mobile version of your site you could create app/mobile_views/users/_form.html.erb and Ress would have Rails select that template over app/views/users/_form.html.erb when a request comes in to the mobile version.

Installation

Add this line to your application's Gemfile:

gem 'ress'

And then execute:

$ bundle install

Run the generator:

$ rails g ress:install

Usage

Adding Alternate Versions

Alternate versions of an application are registered using the #add_alternate method in the ress.rb initializer that is generated by the ress:install generator. The configurabe options available are all documented in the comments of that file.

Version override

You can manually override the version detector javascript and allow mobile clients to visit the canonical version of the app by passing in a the GET url parameter force_canonical=1. This sets a session cookie in a before_filter that stops the version detection scipt from redirecting users, so it only has to be done once per session. Ress includes a helper / controller method force_canonical that returns a link back to the canonical version of the current page with this query param appended. For, example you may include something like this in your <footer> to let mobile users access the canonical site.

<!-- Let mobile devices access the canonical site -->
<footer>
  <% unless canonical_request?  %>
    <div>
      You are currently viewing the mobile version of this site.
      <%= link_to 'View the desktop version', force_canonical_url %>
    </div>
  <% end %>
</footer>

Dependencies

There are a couple of Modernizr features that must be included in order for Ress's javascript feature detection to function. If you are not already using Modernizr in your application you can automatically include a build that has been packaged with the gem by setting config.include_modernizr = true in config/initializers/ress.rb. If you include your own build (recommended), make sure that it includes "Touch Events" and "Media Queries", eg:

http://modernizr.com/download/#-touch-mq-teststyles-prefixes

Performance considerations

The javascript included by Ress does some checks and will use client-side redirection to point users to the right version of your webapp. Client-side redirection can have a performance overhead (though I haven't measured it). If you find this is true, you can keep your DOM the same, still using the SEO-friendly <link rel="alternate"> tags, but simply remove the ress.js script and do your own server-side UA-based redirection.

Browser support

The feature detection javascript should work in all browsers that support document.querySelectorAll. Notably, this excludes IE7. If you want it to work in IE7 and below, please include a polyfill.

Contributing

Given how many browsers and devices we have these days, there are bound to be bugs. If you find them, please report them and (ideally) fix them in a pull request.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Resources

Ress is the compilation of a few different ideas packaged up for Ruby on Rails. You may want to look at the following articles for more info:

Something went wrong with that request. Please try again.