condi 0.0.1

data/LICENSE

@@ -0,0 +1,22 @@
+MIT LICENSE
+from http://www.opensource.org/licenses/mit-license.php
+
+Copyright (C) 2011 by Larry Kyrala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+
+Condi
+=====
+
+Condi is a gem that you use with Rails to make it easier to cleanly implement conditional elements in a view.
+
+Condi allows you to define predicates in the controller that are callable in the view without relying on unneeded instance variables or business logic in the views.  Because the predicates are defined dynamically during a controller action, they are easy to find and easy to use without hopping around multiple files.
+
+API Doc: {Condi}
+
+Copyright (C) 2011 by Larry Kyrala. MIT Licensed.
+
+Example
+-------
+
+For example, say you have a User who has various roles and a shopping Cart that contains items. Your StoreController loads the current User and Cart objects, and your store view displays the User and Cart information.  But let's say that orders over a certain amount for new customers should show a "free ground shipping" option.  With Condi you can do the following:
+
+`app/controllers/store_controller.rb:`
+
+    class StoreController
+      include Condi
+      
+      def checkout
+        user = User.find(user_id)
+        cart = Cart.find(cart_id)
+        predicate(:show_free_shipping?) { user.new_customer? && cart.amount > 100 }
+      end
+    end
+
+`app/views/store/checkout.html.erb:`
+
+    <% form_for @cart do |f| %>
+      <% if show_free_shipping? %>
+        <%= f.radio_button("cart", "shipping", "free_ground") %>
+      <% end %>
+    <% end %> 
+
+The Problem
+-----------
+
+Sometimes, pieces of your UI need to be enabled or disabled depending on certain criteria.  Usually these criteria come from Models loaded during actions in your Controllers.  
+
+Here's a typical implementation of the above example without Condi:
+
+    class StoreController
+      def checkout
+        @user = User.find(user_id)
+        @cart = Cart.find(cart_id)
+      end
+    end
+
+    <% form_for @cart do |f| %>
+      <% if @user.new_customer? && @cart.amount > 100 %>
+        <%= f.radio_button("cart", "shipping", "free_ground") %>
+      <% end %>
+    <% end %> 
+
+Not the cleanest approach since business logic is in our views now.  What's another alternative?  Maybe we can stick a predicate for displaying ground shipping on the Cart model instead?
+
+    class Cart
+      def show_free_shipping?(new_customer)
+        new_customer && amount > 100
+      end
+    end
+
+    <% form_for @cart do |f| %>
+      <% if @cart.show_free_shipping?(@user.new_customer?) %>
+        <%= f.radio_button("cart", "shipping", "free_ground") %>
+      <% end %>
+    <% end %> 
+
+We haven't gained much except shuffling arguments around.
+
+
+Or, we could put the predicate in a helper and remove the args:
+
+    class StoreHelper
+      def show_free_shipping?
+        @user.new_customer? && @cart.amount > 100
+      end
+    end
+  
+    <% form_for @cart do |f| %>
+      <% if show_free_shipping? %>
+        <%= f.radio_button("cart", "shipping", "free_ground") %>
+      <% end %>
+    <% end %> 
+
+This is a little better, but now we have variables set up in the controller and business logic in the helper.  It would be nicer if we could define the predicate in the controller where it is used, in the context of what the action has loaded (either into instance variables or locals).  Also if we have a large data-driven UI, we may have many such conditional UI predicates.  Managing them all can become quite complex.
+
+
+Solution
+--------
+
+The way Condi solves this problem is to allow you to define predicates in the controller that are accessible in the view.
+
+    class StoreController
+      include Condi
+
+      def checkout
+        user = User.find(user_id)
+        cart = Cart.find(cart_id)
+        predicate(:show_free_shipping?) { user.new_customer? && cart.amount > 100 }
+      end
+    end
+
+The `predicate` call creates a closure around the state we've loaded in the controller and makes it available to the view later without cluttering up the helper namespace or forcing the view to contain business logic.
+
+    <% form_for @cart do |f| %>
+      <% if show_free_shipping? %>
+        <%= f.radio_button("cart", "shipping", "free_ground") %>
+      <% end %>
+    <% end %> 
+
+How does this work?  Behind the scenes, `predicate` defines an instance method on the controller and then marks it as a `helper_method` which allows Rails to call the predicate from the view.  Since the predicate is dynamically added, you don't have to worry about the controller instance containing any more predicates than you defined in that particular action, so it's easy to manage.
+
+Advantages
+----------
+
+* Because predicates are closures, there is less of a chance that helpers and controllers and views get "mixed up" -- i.e. someone copies some code from one view to another but forgets to set the correct instance variables in the controller.
+
+* Also, the Model shouldn't define such predicates, because they control behavior in the view, not to mention that predicates can orchestrate several Models together with business logic.  The Controller is arguably a better place to define such predicates from an MVC perspective.
+
+* Condi makes it simple to define predicates in the Controller and call them from the view without cluttering the helper namespace and creating a maze of unique names for every action.  Condi is more flexible.
+
+* Another important advantage of the predicate being defined as an instance method on the Controller during an action-view execution is that the predicate method will never exist on the Controller for subsequent actions -- hence the predicate can never be inadvertently called as an action itself.
+
+
+
+

data/lib/condi.rb

@@ -0,0 +1,22 @@
+# Include this module in an ActionController to define predicates within an action that 
+# can be used later in the related action view. For example:
+#     class StoreController
+#       include Condi
+#       ...
+#     end
+module Condi
+
+	# define a predicate (instance method) on the controller which is callable from the related view. 
+  # @example define a predicate that determines whether or not to show a "free shipping" option.
+  #       predicate(:show_free_shipping?) { user.new_customer? && cart.amount > 100 }
+  # @param [Symbol] method_name name of the predicate method. (e.g. :show_action_button?)
+  # @param [Proc] block {} or do...end block that evaluates to true or false.
+  # @note You are not required to end your method name in a question mark, however it is conventional to do so.
+  # @see the full example in the README 
+ 	def predicate(method_name, &block)
+		self.class.instance_eval do
+			define_method(method_name, &block)
+			helper_method(method_name)
+		end
+	end
+end

data/test/test_condi.rb

@@ -0,0 +1,91 @@
+require 'simplecov'
+SimpleCov.start
+
+require 'test/unit'
+require 'mocha'
+
+require 'action_controller'
+require 'condi'
+
+#require 'ruby-debug'
+
+
+class CondiTest < Test::Unit::TestCase
+  
+  def setup
+    @controller_class = Class.new(::ActionController::Base)
+    @controller_class.instance_eval do
+      include Condi
+    end
+    @controller_instance = @controller_class.new
+  end
+
+  def test_included_properly
+    assert @controller_instance.respond_to?(:predicate)
+  end
+
+  def test_simple_predicate
+    @controller_instance.instance_eval do 
+      predicate(:always_true?) { true }
+    end
+
+    assert @controller_instance.respond_to?(:always_true?)
+    assert @controller_instance.always_true? == true
+  end
+
+  def test_instance_variable_predicate
+    @controller_instance.instance_eval do 
+      @var = 5
+      predicate(:is_var_5?) { @var == 5 }
+    end
+    
+    assert @controller_instance.respond_to?(:is_var_5?)
+    assert @controller_instance.is_var_5? == true    
+  end
+
+  def test_local_variable_predicate
+    @controller_instance.instance_eval do 
+      var = "Mary"
+      predicate(:is_mary?) { (var =~ /Mary/) == 0 }
+    end
+
+    assert @controller_instance.respond_to?(:is_mary?)
+    assert @controller_instance.is_mary? == true    
+  end
+
+  def test_complex_multiline_predicate
+    @controller_instance.instance_eval do 
+      # simulating loaded AR objects in a controller method.
+      @customer = Object.new
+      def @customer.new_customer?
+        true 
+      end
+      @cart = Object.new
+      def @cart.amount
+        105
+      end
+      predicate(:show_free_shipping?) do
+        @customer.new_customer? && @cart.amount > 100 
+      end
+    end
+    
+    assert @controller_instance.respond_to?(:show_free_shipping?)
+    assert @controller_instance.show_free_shipping? == true    
+  end
+
+  def test_exception_within_predicate
+    @controller_instance.instance_eval do
+      predicate(:blows_up?) do
+        raise "blew up!"
+      end
+    end
+
+    assert @controller_instance.respond_to?(:blows_up?)
+    assert_raise RuntimeError do
+      puts "ah ha!" if @controller_instance.blows_up?
+    end    
+    
+  end
+
+
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: condi
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Larry Kyrala
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-14 00:00:00.000000000 Z
+dependencies: []
+description: Conditional UI predicates for Rails
+email: larry.kyrala@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/condi.rb
+- README.md
+- LICENSE
+- test/test_condi.rb
+homepage: http://github.com/coldnebo/condi
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- rails
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Condi
+test_files:
+- test/test_condi.rb