mobile_view 0.2.0 → 0.3.0

data/.gitignore

@@ -5,3 +5,6 @@ spec/dummy/db/*.sqlite3
 spec/dummy/log/*.log
 spec/dummy/tmp/
 spec/dummy/.sass-cache
+.yardoc/
+doc/
+.DS_Store

data/.yardopts

@@ -0,0 +1,3 @@
+--protected
+--no-private
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mobile_view (0.2.0)
+    mobile_view (0.3.0)
       rack-mobile-detect (~> 0.4.0)
       rails (~> 3.2.0)
 

data/README.markdown

@@ -1,48 +1,104 @@
 # MobileView
 
-Rails view template for mobile devices made easy.
+Easily specify mobile-specific view template for mobile devices in Rails application.
+
+**Warning** This gem still has major version of `0` which means it's during early alpha and APIs and usages are subject to change. Strategies and implementations may not be the best practice. Bugs may exist. Feel free to send patches for everyting that you think it's not good or would like to change. I'll add your name to README after approved.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem "mobile_view", "~> 0.2.0"
+    gem "mobile_view", "~> 0.3.0"
 
 And then execute:
 
     $ bundle
 
+Add these lines into your base controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  has_mobile_view
+end
+```
+
 ## Dependency
 
   * Rails 3.2.x
 
+Development dependency:
+
+  * RSpec
+  * Capybara
+  * [PhantomJS](http://phantomjs.org/) (Capybara's integration test is driven by [poltergeist](https://github.com/jonleighton/poltergeist), for easier cookie and header modification.)
+
 ## Usage
 
 ### `action.mobile.html.erb` View Template
 
-#### Scenario
+If you have problems like this:
+
+1. You have a view template for `posts#show`, with many DOM elements and JavaScripts, which is good for desktop, but painful for mobile devices. (In such case even Responsive Web Design with CSS media queries doesn't help you much.)
+* You're tired of `<%= render_something if mobile? %>` conditional hell.
+* You want to make a mobile-friendly view, which is mostly different from desktop version, build form scratch.
 
-You have a view template for `posts#show`, with many DOM elements and JavaScripts, which is good for desktop, but painful for mobile devices. You're tired of `<%= render_something if mobile? %>` conditional hell. You want to make it mobile-friendly, with a view that is mostly different form scratch.
+With MobileView, you can add `posts/show.mobile.html.erb` along with `posts/show.html.erb`. Then, if the browser is a mobile device, Rails will choose the mobile template first:
 
-#### Solution
+* <tt>posts/show.html.erb</tt> = default view for `posts#show`
+* <tt>posts/show<b>.mobile</b>.html.erb</tt> = mobile view for `posts#show`
 
-Add `posts/show.mobile.html.erb` along with `posts/show.html.erb`. If the browser is a mobile device, then Rails will choose the mobile template first.
+It also works for partial views and layout views:
 
-It works for any format handlers (`erb`, `haml` etc.) and formats (`json`, `js`, `xml` etc.) available in your Rails application. You just have to add `mobile` after the view's name.
+* <tt>posts/_post.html.erb</tt> = default view for partial view `posts/post`
+* <tt>posts/_post<b>.mobile</b>.html.erb</tt> = mobile view for partial view `posts/post`
 
-It also works for partial views. When a mobile version of partial view is not available, it will choose non-mobile version automatically. You just have to add `mobile` after the view's name.
+and
 
-It also works for layout view. So you can now use `views/layouts/application.mobile.html.erb` for mobile devices.
+* <tt>layouts/application.html.erb</tt> = default layout
+* <tt>layouts/application<b>.mobile</b>.html.erb</tt> = mobile layout
+
+#### ERb, HAML; JSON, JavaScript etc. All Supported.
+
+You can use any template handlers (`erb`, `haml` etc.) and formats (`json`, `js`, `xml` etc.) available in your Rails application.  All you have to do is add another view template with `mobile` after the view's main name (before locale, format and handler). It follows the naming rule of Rails's view template files; the only difference is the `.mobile` interpolation:
+ 
+* <tt>prefix/name<i>.locale.format.handler</i></tt> = default view
+* <tt>prefix/name<b>.mobile</b><i>.locale.format.handler</i></tt> = mobile view
+
+#### Auto Fallback
+
+When a mobile version of partial view is not available, it will automatically fallback to default (non-mobile) version.
 
 ### `mobile?` Helper
 
-Still want to detect mobile device in Controller and View? Use `mobile?` helper. It returns `true` if it thinks the browser is a mobile device, `false` otherwise.
+The `mobile?` helper tells you if currently MobileView switched to mobile version or not. It is available in controller and view.
+
+The situation of "switched to mobile view" could be:
+
+* accessing with a mobile device browser, or
+* manually switched to mobile view (see [cookie-based switching](#cookie-based-mobile-view-switching) below).
+
+Returns `true` if it switched to mobile view, `false` otherwise.
+
+Example:
+
+```ruby
+# in controller
+@text += "Hello! Mobile" if mobile?
+```
+
+```erb
+<%# in view %>
+<%= render_advertisement unless mobile? %>
+```
+
+#### Mounted Engine
 
 To use `mobile?` helper in a mounted engine, for example, [Rails Cell](https://github.com/apotonick/cells), simply include the `MobileView::ControllerAdditions` module:
 
 ```ruby
 class PostCell < Cell::Rails
   include MobileView::ControllerAdditions
+  has_mobile_view
 end
 ```
 
@@ -50,21 +106,31 @@ end
 
 By setting `mobile` cookie, you can force it to load mobile views. This is helpful when debugging the app in desktop browsers, or allowing user to switch to mobile version manually.
 
+The cookie injection of manual switching should happen **before** `has_mobile_view` is invoked.
+
 Example:
 
 ```ruby
 class AppliactionController < ActionController::Base
   before_filter :manual_mobile_switching
 
+  has_mobile_view
+
   protected
   # Detects `_mobile_view` parameter.
-  # If it is any value other than 0, turn on mobile view,
-  # otherwise, turn off mobile view.
-  def manual_mobile_switching
-    if params[:_mobile_view] != "0"
-      cookies["mobile"] = true # or anything other than falsy value
-    else
-      cookies.delete "mobile" # remove `mobile' cookie
+  #
+  # If it is 'yes', force turn on mobile view by setting cookie mobile=1;
+  # if it is 'no', force turn off mobile view by setting cookie mobile=0;
+  # if it is 'auto', remove mobile cookie and fallback to User-Agent mode;
+  # otherwise, no effect.
+  def mobile_switching
+    case params[:_mobile_view]
+    when 'yes'
+      force_mobile!
+    when 'no'
+      force_non_mobile!
+    when 'auto'
+      dismiss_mobile_forcing!
     end
   end
 end
@@ -76,6 +142,17 @@ end
 
 According to the algorithm of [Rack::MobileDetect](https://github.com/talison/rack-mobile-detect/), iPad will be seen as a Mobile Device. This may be a fail assumption if you want to show your desktop website to iPad and tablet users. This can (may) be resolved by replacing mobile device detection logic or add more tablet-specific methods.
 
+Workaround: Force switch to non-mobile version when client is iPad:
+
+```ruby
+class AppliactionController < ActionController::Base
+  before_filter :force_non_mobile!, :if => :ipad?
+
+  # still have to invoke has_mobile_view after force_mobile!
+  has_mobile_view
+end
+```
+
 ## References
 
 * [#269 Template Inheritance - RailsCasts](http://railscasts.com/episodes/269-template-inheritance)
@@ -84,10 +161,15 @@ According to the algorithm of [Rack::MobileDetect](https://github.com/talison/ra
 
 ## Changelog
 
+### 0.3.0
+
+* [breaking] Fron now on you have to invoke `has_mobile_view` in controller explicitly.
+* Wrap cookie-based switching into a bunch of helper methods for code readability.
+
 ### 0.2.0
 
 * Support cookie-based switching
-* Rename helper `mobile_device?` to `mobile?` since it now not only detects mobile device, but also accepts cookie-based switching.
+* [breaking] Rename helper `mobile_device?` to `mobile?` since it now not only detects mobile device, but also accepts cookie-based switching.
 * Ability to have other mounted engines use `mobile?` helper. (Inspired from [Devise](https://github.com/plataformatec/devise/blob/v2.1.2/lib/devise/controllers/helpers.rb))
 
 ### 0.1.0
@@ -95,7 +177,7 @@ According to the algorithm of [Rack::MobileDetect](https://github.com/talison/ra
 :birthday: First Release
 
 * `*.mobile` view template auto-overriding
-* Automatically mobile device detection
+* Automatic mobile device detection
 * `mobile_device?` helper for controller and view
 
 ## License

data/lib/mobile_view/controller_additions.rb

@@ -1,20 +1,60 @@
+require 'mobile_view/forced_switching'
+
 module MobileView
   module ControllerAdditions
     extend ActiveSupport::Concern
 
-    included do
+    include MobileView::ForcedSwitching::ControllerAdditions
+
+    included do |base|
+      base.extend ClassMethods
+
       # make mobile? method a view helper too
       helper_method :mobile?
+    end
+
+    module ClassMethods
+      # Install MobileView into a Controller.
+      #
+      # By invoking this method, a view-path resolver will be prepended
+      # before all the existing resolvers, immediately. If you're going
+      # to force mobile switching (see {ForcedSwitching}),
+      # then you have to invoke them before +has_mobile_view+.
+      #
+      # == Example
+      #
+      # Present non-mobile version to iPad users:
+      #
+      #   class ApplicationController < ActionController::Base
+      #     before_filter :force_non_mobile!, :if => :ipad?
+      #
+      #     has_mobile_view
+      #   end
+      #
+      def has_mobile_view
 
-      # find mobile view templates first, if mobile device is detected.
-      before_filter do
-        prepend_view_path(MobileView.resolver) if mobile?
+        # find mobile view templates first, if mobile device is detected.
+        self.before_filter do
+          prepend_view_path(MobileView.resolver) if mobile?
+        end
       end
     end
 
     protected
+    # Test if currently MobileView uses mobile version of view templates.
+    #
+    # Situations of "use mobile version" is be determined by the following algorithm:
+    #
+    # 1. If using {ForcedSwitching::ControllerAdditions forced switching}, then test if force switched to mobile version.
+    # 2. Otherwise, automatically test by User-Agent (done by {https://github.com/talison/rack-mobile-detect Rack::MobileDetect}).
+    #
+    # @return {Boolean}
     def mobile?
-      cookies[:mobile].present? || request.headers["X_MOBILE_DEVICE"].present?
+      if mobile_forcing?
+        return forced_mobile?
+      else
+        return request.headers["X_MOBILE_DEVICE"].present?
+      end
     end
   end
 end

data/lib/mobile_view/forced_switching.rb

@@ -0,0 +1,107 @@
+module MobileView
+  module ForcedSwitching
+    # The name of cookie which remembers forced mobile view switching.
+    COOKIE_NAME = "mobile"
+
+    # Value of the cookie to represent "forced to mobile view".
+    FORCE_MOBILE_VALUE = "1"
+
+    # Value of the cookie to represent "forced to non-mobile view".
+    FORCE_NON_MOBILE_VALUE = "0"
+
+    # These controller additions are helpers that you can use
+    # in your controller to test if currently it is forcely (manually) switched to mobile 
+    # version, or non-mobile version.
+    #
+    # By force-switching to either version, MobileView will take it at the top
+    # precedence, and ignore the ascending methods (e.g. by User-Agent).
+    #
+    # Force-switching should happen before {MobileView::ControllerAdditions::ClassMethods#has_mobile_view has_mobile_view}
+    # is invoked. See {MobileView::ControllerAdditions::ClassMethods#has_mobile_view has_mobile_view}'s example.
+    #
+    # They will be automatically included into the controller
+    # that includes {MobileView::ControllerAdditions}. You don't need to
+    # <tt>include</tt> this module manually.
+    #
+    # TODO: Unit Testing
+    #
+    # == Examples
+    #
+    # === Use as before filters
+    #
+    #   class AppliactionController < ActionController::Base
+    #     before_filter :force_mobile!, :if => :ie6?
+    #     before_filter :force_non_mobile!, :if => :ipad?
+    #     has_mobile_view
+    #   end
+    #
+    # === Manual Mobile Switching
+    #
+    # A user can manually switch to mobile version or non-mobile version by specifying `_mobile_view` parameter.
+    #
+    # For example:
+    #
+    # * <tt>?_mobile_view=yes</tt> switches to mobile view.
+    # * <tt>?_mobile_view=no</tt> switches to non-mobile view.
+    # * <tt>?_mobile_view=auto</tt> don't force switch; determine by User-Agent.
+    #
+    # To accomplish the logic above:
+    #
+    #   class AppliactionController < ActionController::Base
+    #     before_filter :manual_mobile_switching
+    #
+    #     has_mobile_view
+    #
+    #     protected
+    #
+    #     # Detects `_mobile_view` parameter.
+    #     #
+    #     # If it is 'yes', force turn on mobile view by setting cookie mobile=1;
+    #     # if it is 'no', force turn off mobile view by setting cookie mobile=0;
+    #     # if it is 'auto', remove mobile cookie and fallback to User-Agent mode;
+    #     # otherwise, no effect.
+    #     def mobile_switching
+    #       case params[:_mobile_view]
+    #       when 'yes'
+    #         force_mobile!
+    #       when 'no'
+    #         force_non_mobile!
+    #       when 'auto'
+    #         dismiss_mobile_forcing!
+    #       end
+    #     end
+    #   end
+    module ControllerAdditions
+      protected
+      # Force switch to mobile view.
+      def force_mobile!
+        cookies[COOKIE_NAME] = FORCE_MOBILE_VALUE
+      end
+
+      # Force switch to non-mobile (default) view.
+      def force_non_mobile!
+        cookies[COOKIE_NAME] = FORCE_NON_MOBILE_VALUE
+      end
+
+      # Dismiss any forced switching, and fallback to other methods like User-Agent sniffing
+      def dismiss_mobile_forcing!
+        cookies.delete COOKIE_NAME
+      end
+
+      # Test if currently forced to mobile or non-mobile view.
+      def mobile_forcing?
+        forced_mobile? || forced_non_mobile?
+      end
+
+      # Test if currently forced to mobile view.
+      def forced_mobile?
+        cookies[COOKIE_NAME] == FORCE_MOBILE_VALUE
+      end
+
+      # Test if currently forced to non-mobile view.
+      def forced_non_mobile?
+        cookies[COOKIE_NAME] == FORCE_NON_MOBILE_VALUE
+      end
+    end
+  end
+end

data/lib/mobile_view/resolver.rb

@@ -1,7 +1,41 @@
 module MobileView
+
+  # Resolver for mobile view templates; search for +*.mobile+ templates.
+  #
+  # When invoking {ControllerAdditions::ClassMethods#has_mobile_view has_mobile_view}, and MobileView thinks
+  # it should choose mobile version first, this resolver will be prepended to the
+  # existing +view_paths+, makes it become the first precedence of template searching.
+  #
+  # Searching is done by finding templates with the following pattern, which is same as
+  # the convension of template file naming rule, except for +.mobile+ injection:
+  #
+  #   prefix/action.mobile.locale.formats.handlers
+  #                ^^^^^^^
+  #                hard-coded
+  #
+  # Pattern is modified from {https://github.com/rails/rails/blob/v3.2.9/actionpack/lib/action_view/template/resolver.rb#L106 ActionView::PathResolver}
+  #
+  # == Algorithm Explanation
+  #
+  # For example, when there exists the following two templates:
+  #
+  # * posts/show.html.erb
+  # * posts/show.mobile.html.erb
+  #
+  # When MobileView thinks currently it is switched to mobile version (see {ControllerAdditions#mobile?}),
+  # then a {Resolver} will be prepended to the search pathes,
+  # and Rails will get +posts/show.mobile.html.erb+ as the first available template.
+  # When MobileView thinks it is not switched to mobile version, then this {Resolver} will not be
+  # prepended, and Rails will search for templates as usual.
+  #
+  # Since Rails's template searching is implemented by auto-fallback strategy,
+  # if a corresponding +*.mobile+ doesn't exist, then this {Resolver}
+  # will return nothing, and Rails will automatically use other resolvers.
+  #
   class Resolver < ::ActionView::FileSystemResolver
-    # pattern is modified from ActionView
-    # https://github.com/rails/rails/blob/v3.2.9/actionpack/lib/action_view/template/resolver.rb#L106
+    # <tt>prefix/action<b>.mobile</b>.locale.formats.handlers</tt>
+    #
+    # Example: <tt>posts/show<b>.mobile</b>.html.erb</tt>
     MOBILE_PATTERN = ":prefix/:action.mobile{.:locale,}{.:formats,}{.:handlers,}"
 
     def initialize(path)

data/lib/mobile_view/version.rb

@@ -1,3 +1,3 @@
 module MobileView
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/spec/dummy/app/controllers/application_controller.rb

@@ -1,3 +1,5 @@
 class ApplicationController < ActionController::Base
   protect_from_forgery
+
+  has_mobile_view
 end

data/spec/features/mobile_view_spec.rb

@@ -8,9 +8,9 @@ def use_iphone
   page.driver.headers = { "User-Agent" => IPHONE_USER_AGNET }
 end
 
-def set_mobile_cookie
+def set_mobile_cookie(value)
   # depends on poltergeist
-  page.driver.set_cookie "mobile", true
+  page.driver.set_cookie "mobile", value
 end
 
 describe "View Template Overriding" do
@@ -51,9 +51,9 @@ describe "View Template Overriding" do
     end
   end
 
-  context "when client provides mobile cookie" do
+  context "when client set cookie mobile=1" do
     before :each do
-      set_mobile_cookie
+      set_mobile_cookie("1")
     end
 
     it "renders mobile-specific action view template" do
@@ -88,6 +88,43 @@ describe "View Template Overriding" do
     end
   end
 
+  context "when client is mobile browser and set cookie mobile=0" do
+    before :each do
+      set_mobile_cookie("0")
+    end
+
+    it "renders default action view template" do
+      visit "/pages/action_view"
+
+      page.should have_selector('#default-view')
+    end
+
+    it "renders default partial view template" do
+      visit "/pages/partial_view"
+
+      page.should have_selector('#default-partial-view')
+    end
+
+    it "renders default layout view template" do
+      visit "/pages/layout_template"
+
+      page.should have_selector('body.desktop')
+    end
+
+    it "renders default view template when there is no mobile-specific overriding" do
+      visit "/pages/default"
+
+      page.should have_selector('#hello-world')
+    end
+
+    it "renders general content" do
+      visit "/pages/conditional"
+
+      page.should have_selector('#non-mobile-device')
+      page.should have_content('Hi Desktop!')
+    end
+  end
+
   context "when client is not mobile browser" do
     it "renders default action view template" do
       visit "/pages/action_view"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mobile_view
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-22 00:00:00.000000000 Z
+date: 2012-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -101,6 +101,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - README.markdown
@@ -108,6 +109,7 @@ files:
 - lib/mobile_view.rb
 - lib/mobile_view/controller_additions.rb
 - lib/mobile_view/engine.rb
+- lib/mobile_view/forced_switching.rb
 - lib/mobile_view/resolver.rb
 - lib/mobile_view/version.rb
 - lib/tasks/mobile_view_tasks.rake
@@ -170,7 +172,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 232344584105567251
+      hash: 2535113380593733321
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -179,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 232344584105567251
+      hash: 2535113380593733321
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24