RubyGems - ress - Versions diffs - 0.0.6 → 0.0.7 - Mend

ress 0.0.6 → 0.0.7

Files changed (10) hide show

data/README.md +48 -32
data/lib/ress.rb +1 -0
data/lib/ress/canonical_version.rb +14 -18
data/lib/ress/subdomain.rb +78 -0
data/lib/ress/version.rb +1 -1
data/spec/ress/canonical_version_spec.rb +1 -15
data/spec/ress/category_collection_spec.rb +2 -2
data/spec/ress/subdomain_spec.rb +112 -0
data/spec/ress_spec.rb +1 -1
metadata +5 -2

data/README.md CHANGED

@@ -16,7 +16,7 @@ for which devices should be redirected to which version.
 ### HTML Annotations
 When you register alternate mobile versions of your website, Ress adds annotations
-to the `<head>` of your document that describes where these pages are located and
+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
@@ -34,22 +34,18 @@ version:
 ```
 These annotations conform to SEO best practices for mobile optimized websites
-as documented by Google
-[here](https://developers.google.com/webmasters/smartphone-sites/details).
+[as documented by Google](https://developers.google.com/webmasters/smartphone-sites/details).
 ### Feature Detection
-Device.js will read all of the version links in your markup, and
-redirect you to the appropriate URL that serves the correct version of
-your webapp.
-When a request comes into your site, ress runs a some javascript 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.
+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 requests in
+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
@@ -64,7 +60,7 @@ been requested. This is useful for small tweeks in html or behaviour, eg:
 ```
 2. It prepends a view path for each alternate version of your site, so that you can
-override which templates or partials are rendered for certain requests. For example if
+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
@@ -81,34 +77,38 @@ And then execute:
     $ bundle install
-Run the installation generator:
+Run the generator:
     $ rails g ress:install
 ## Usage
-### Version override
+### Adding Alternate Versions
-You can manually override the detector and load a particular version of
-the site by passing in the `device` GET parameter with the ID of the
-version you'd like to load. This will look up the `link` tag based on
-the specified ID and load that version. For example, if you are on
-desktop but want the tablet version, visiting
-`http://foo.com/?version=tablet` will redirect to the tablet version at
-`http://tablet.foo.com`.
+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](https://github.com/matthewrobertson/ress/blob/master/lib/generators/ress/templates/ress.rb).
-Relatedly, you can prevent redirection completely, by specifying the
-`force=1` GET parameter. For example, if you are on desktop and know the
-URL of the tablet site, you can load `http://tablet.foo.com/?force=1`.
+### Version override
-```html
-<!-- Include a way to manually switch between device types -->
+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.
+```erb
+<!-- Let mobile devices access the canonical site -->
 <footer>
-  <ul>
-    <li><a href="?device=desktop">Desktop</a></li>
-    <li><a href="?device=tablet">Tablet</a></li>
-    <li><a href="?device=phone">Phone</a></li>
-  </ul>
+  <% 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>
 ```
@@ -130,7 +130,7 @@ 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 pushing.
+ress.js script and do your own server-side UA-based redirection.
 ## Browser support
@@ -149,3 +149,19 @@ in a pull request.
 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:
+- [devicejs](https://github.com/borismus/device.js) -  a javascript library for client
+side feature direction and the main inspiration for this gem. Boris has also provided
+[a good write up about it](http://www.html5rocks.com/en/mobile/cross-device/) on
+http://www.html5rocks.com/
+- [Building Smartphone-Optimized Websites](https://developers.google.com/webmasters/smartphone-sites/details) - Google's
+recommendations and best practices for building Mobile Optimized web apps
+- [RESS: Responsive Design + Server Side Components](http://www.lukew.com/ff/entry.asp?1392) - an
+article by Luke Wroblewski about combining Responsive Design and Server Side Components (the
+inspiration for the name RESS).

data/lib/ress.rb CHANGED

@@ -1,6 +1,7 @@
 require "action_view"
 require "ress/version"
+require "ress/subdomain"
 require "ress/alternate_version"
 require "ress/canonical_version"
 require "ress/category_collection"

data/lib/ress/canonical_version.rb CHANGED

@@ -2,35 +2,31 @@ module Ress
   class CanonicalVersion
-    attr_reader :subdomain
     def initialize(options = {})
-      @subdomain = options.fetch(:subdomain, false)
+      @subdomain = Ress::Subdomain.create(options.fetch(:subdomain, nil))
     end
-    def matches?(subdomain)
-      if self.subdomain
-        self.subdomain == subdomain
-      else
-        subdomain.empty?
-      end
+    def matches?(req_subdomain)
+      subdomain.matches?(req_subdomain)
     end
     # Create a tag of this format:
     #  `<link rel="canonical" href="http://www.example.com/page-1" >`
-    def link_tag(protocol, fullpath, subdomain, view)
-      view.tag :link, :rel => 'canonical', :href => url(protocol, fullpath, subdomain)
+    def link_tag(protocol, fullpath, req_subdomain, view)
+      view.tag :link, :rel => 'canonical', :href => url(protocol, fullpath, req_subdomain)
     end
-    def url(protocol, fullpath, subdomain)
-      fullpath = fullpath[(subdomain.length + 1)..-1] unless subdomain.empty?
-      if self.subdomain
-        "#{protocol}#{self.subdomain}.#{fullpath}"
-      else
-        "#{protocol}#{fullpath}"
-      end
+    def url(protocol, fullpath, req_subdomain)
+      subdomain.url(protocol, fullpath, req_subdomain)
     end
+    private
+      def subdomain
+        @subdomain
+      end
   end
 end

data/lib/ress/subdomain.rb ADDED

@@ -0,0 +1,78 @@
+module Ress
+  class Subdomain
+    # this class is a factory, don't instantiate it directly
+    private_class_method :new
+    def self.create(subdomain)
+      case subdomain
+      when String
+        StringSubdomain.new(subdomain)
+      when Regexp
+        RegexpSubdomain.new(subdomain)
+      else
+        NilSubdomain.new
+      end
+    end
+    class NilSubdomain
+      def matches?(subdomain)
+        subdomain.empty?
+      end
+      def url(protocol, fullpath, subdomain)
+        fullpath = fullpath[(subdomain.length + 1)..-1] unless subdomain.empty?
+        "#{protocol}#{fullpath}"
+      end
+    end
+    class StringSubdomain
+      attr_reader :subdomain
+      def initialize(subdomain)
+        @subdomain = subdomain
+      end
+      def matches?(subdomain)
+        self.subdomain == subdomain
+      end
+      def url(protocol, fullpath, subdomain)
+        fullpath = fullpath[(subdomain.length + 1)..-1] unless subdomain.empty?
+        "#{protocol}#{self.subdomain}.#{fullpath}"
+      end
+    end
+    # The main inspiration for this class is to match xip.io
+    # subdomains for many devs working in development mode with
+    # the same configuration.
+    class RegexpSubdomain
+      attr_reader :subdomain
+      def initialize(subdomain)
+        @subdomain = subdomain
+      end
+      def matches?(subdomain)
+        self.subdomain =~ subdomain
+      end
+      def url(protocol, fullpath, subdomain)
+        fullpath = fullpath[(subdomain.length + 1)..-1]
+        begin
+          if matches?(subdomain)
+            return "#{protocol}#{subdomain}.#{fullpath}"
+          end
+          subdomain = subdomain.split('.')[1..-1].join('.')
+        end while(!subdomain.empty?)
+      end
+    end
+  end
+end

data/lib/ress/version.rb CHANGED

@@ -1,3 +1,3 @@
 module Ress
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end

data/spec/ress/canonical_version_spec.rb CHANGED

@@ -1,21 +1,7 @@
-require_relative '../../lib/ress/canonical_version'
+require_relative '../../lib/ress'
 describe Ress::CanonicalVersion do
-  describe '#subdomain' do
-    it 'defaults to false' do
-      category = Ress::CanonicalVersion.new
-      category.subdomain.should == false
-    end
-    it 'can be overridden by an optional parameter' do
-      category = Ress::CanonicalVersion.new(:subdomain => 'foo')
-      category.subdomain.should == 'foo'
-    end
-  end
   describe '#matches?' do
     context 'with no canonical subdomain' do

data/spec/ress/category_collection_spec.rb CHANGED

@@ -27,12 +27,12 @@ describe Ress::CategoryCollection do
   describe 'canonical_version' do
     it 'defaults to a canonical_version with no subdomain' do
-      collection.canonical_version.subdomain.should be_false
+      collection.canonical_version.matches?('').should be_true
     end
     it 'can be altered through set_canonical' do
       collection.set_canonical :subdomain => 'foo'
-      collection.canonical_version.subdomain.should == 'foo'
+      collection.canonical_version.matches?('foo').should be_true
     end
   end

data/spec/ress/subdomain_spec.rb ADDED

@@ -0,0 +1,112 @@
+require_relative '../../lib/ress/subdomain'
+describe Ress::Subdomain do
+  describe '.create' do
+    it 'returns a NilSubdomain when the subdomain is nil' do
+      Ress::Subdomain.create(nil).should be_a(Ress::Subdomain::NilSubdomain)
+    end
+    it 'returns a StringSubdomain when the subdomain is a String' do
+      Ress::Subdomain.create('foo').should be_a(Ress::Subdomain::StringSubdomain)
+    end
+    it 'returns a RegexpSubdomain when the subdomain is a Regex' do
+      Ress::Subdomain.create(/foo/).should be_a(Ress::Subdomain::RegexpSubdomain)
+    end
+  end
+  describe Ress::Subdomain::NilSubdomain do
+    let(:subdomain) { Ress::Subdomain::NilSubdomain.new }
+    describe '#matches?' do
+      it 'matches the empty string' do
+        subdomain.matches?('').should be_true
+        subdomain.matches?('s').should be_false
+      end
+    end
+    describe '#url' do
+      it 'strips urls from the fullpath if there is one' do
+        subdomain.url('http://', 'foo.bar.com/some/stuff', 'foo').should ==
+          'http://bar.com/some/stuff'
+      end
+      it 'concatenates the protocol and fullpath together if there is no subdomain' do
+        subdomain.url('http://', 'bar.com/some/stuff', '').should ==
+          'http://bar.com/some/stuff'
+      end
+    end
+  end
+  describe Ress::Subdomain::StringSubdomain do
+    let(:subdomain) { Ress::Subdomain::StringSubdomain.new('foo') }
+    describe '#matches?' do
+      it 'returns true if the url is exact match of that passed to the ctor' do
+        subdomain.matches?('foo').should be_true
+      end
+      it 'returns false if the url is not an exact match of that passed to the ctor' do
+        subdomain.matches?('boo').should be_false
+      end
+    end
+    describe '#url' do
+      it 'strips off extra subdomains from the fullpath' do
+        subdomain.url('http://', 'm.foo.bar.com/some/stuff', 'm.foo').should ==
+        'http://foo.bar.com/some/stuff'
+      end
+      it 'handles cannonical fullpaths' do
+        subdomain.url('http://', 'foo.bar.com/some/stuff', 'foo').should ==
+        'http://foo.bar.com/some/stuff'
+      end
+    end
+  end
+  describe Ress::Subdomain::RegexpSubdomain do
+    describe '#matches?' do
+      let(:subdomain) { Ress::Subdomain::RegexpSubdomain.new(/[fb]oo/) }
+      it 'returns true if the subdomain matches regex that passed to the ctor' do
+        subdomain.matches?('foo').should be_true
+        subdomain.matches?('boo').should be_true
+      end
+      it 'returns false if the subdomain doesnt matches regex that is passed to the ctor' do
+        subdomain.matches?('baz').should be_false
+      end
+      it 'can handle the xip.io format' do
+        subdomain = Ress::Subdomain::RegexpSubdomain.new(/^([0-9]+\.){3}([0-9]+)/)
+        subdomain.matches?('172.30.251.3').should be_true
+        subdomain.matches?('mobile.172.30.251.3').should be_false
+      end
+    end
+    describe '#url' do
+      let(:subdomain) { Ress::Subdomain::RegexpSubdomain.new(/^[fb]oo/) }
+      it 'echos back the url for cannonical requests' do
+        subdomain.url('http://', 'foo.bar.com/some/stuff', 'foo').should ==
+        'http://foo.bar.com/some/stuff'
+      end
+      it 'strips off prepended subdomains that dont matche the regex' do
+        subdomain.url('http://', 'm.a.foo.bar.com/some/stuff', 'm.a.foo').should ==
+        'http://foo.bar.com/some/stuff'
+      end
+    end
+  end
+end

data/spec/ress_spec.rb CHANGED

@@ -18,7 +18,7 @@ describe Ress do
     it 'can be altered through Ress.configure' do
       Ress.configure { |r| r.set_canonical :subdomain => 'foo' }
-      Ress.canonical_version.subdomain.should == 'foo'
+      Ress.canonical_version.matches?('foo').should be_true
     end
   end

metadata CHANGED

@@ -2,14 +2,14 @@
 name: ress
 version: !ruby/object:Gem::Version
   prerelease:
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Matthew Robertson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-01-29 00:00:00.000000000 Z
+date: 2013-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
@@ -65,6 +65,7 @@ files:
 - lib/ress/category_collection.rb
 - lib/ress/controller_additions.rb
 - lib/ress/engine.rb
+- lib/ress/subdomain.rb
 - lib/ress/version.rb
 - lib/ress/view_helpers.rb
 - ress.gemspec
@@ -72,6 +73,7 @@ files:
 - spec/ress/canonical_version_spec.rb
 - spec/ress/category_collection_spec.rb
 - spec/ress/controller_additions_spec.rb
+- spec/ress/subdomain_spec.rb
 - spec/ress/view_helpers_spec.rb
 - spec/ress_spec.rb
 - vendor/assets/javascripts/ress.js
@@ -105,5 +107,6 @@ test_files:
 - spec/ress/canonical_version_spec.rb
 - spec/ress/category_collection_spec.rb
 - spec/ress/controller_additions_spec.rb
+- spec/ress/subdomain_spec.rb
 - spec/ress/view_helpers_spec.rb
 - spec/ress_spec.rb