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

ress 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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