context_exposer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2452c12a649755432297fcee4e4fefb40b864313
-  data.tar.gz: 8ace695b9b00d9f114874aa9b5719064c64a0c83
+  metadata.gz: cff7846013a27d16f62e455b571af3336ea88531
+  data.tar.gz: d7b782a83befc4da2b8ffa9a145eff505734d303
 SHA512:
-  metadata.gz: 78721b922904ab3222e41024042691c3998103414314a5f4adf75bf8b34fd6c9a529c7acee68c23af948219b3577727276ffb1c617fd8d1ed21dc93a92484d47
-  data.tar.gz: c0bcbf8cb1781b7fc39f0b1d6246c7b11f931056925f64becd31ab19f3e76606b996b4faa5e67470ec8c407c4dc86bb9ba4c369fe7bfae23330a33f1914bec34
+  metadata.gz: 47926e8db084652454e11b10b82e949618809ed3a1b9141c98b5830dae93a5e771fe79aca837a7a1520062710b9c3fe5f4a7cf63366942048db414391b7e1f36
+  data.tar.gz: 191e35391a9271b9cc3a3dea8e2429fee8ebb0c6788ade0feb2f9c449303c280fc6bcf26c3d2bf3151db1dcc94db809fff341c87fcd9a91a0717a885785e7553

data/Gemfile

@@ -4,5 +4,17 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rails', '>= 3.1'
+gem "rspec",       '>= 2.0', group: [:test, :development]
 gem "rspec-rails", '>= 2.0', group: [:test, :development]
-gem 'pry',         group: [:development]
+gem 'pry',         group: [:development]
+
+group :test do
+  gem 'capybara', '>= 2.0'
+  gem 'spork-rails', '>= 3.0'
+
+  gem 'decent_exposure'
+  gem 'decorates_before_rendering', github: 'ohwillie/decorates_before_rendering'
+
+  # gem 'factory_girl_rails', '>= 3.0'
+  # gem 'database_cleaner', '>= 0.7'
+end

data/README.md

@@ -7,6 +7,14 @@ No more pollution of the View with content helper methods or even worse, instanc
 
 The Context object will by default be an instance of `ContextExposer::ViewContext`, but you can subclass this baseclass to add you own logic for more complex scenarios. This also allows for a more modular approach, where you can easily share or subclass logic between different view contexts. Nice!
 
+The gem comes with integrations ready for easy migration or symbiosis with existing strategies (and gems), such as:
+
+* exposing of instance variables (Rails default strategy)
+* decent_exposure gem (expose methods)
+* decorates_before_rendering gem (expose decorated instance vars)
+
+For more on integration (and migration path) see below ;)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -36,15 +44,44 @@ class PostsController < ActionController::Base
 end
 ```
 
+The view will have the methods exposed and available on the `ctx` object.
+
 HAML view example
 
 ```haml
 %h1 Posts
-= context.posts.each do |post|
+= ctx.posts.each do |post|
   %h2 = post.name
 ```
 
-You can also define your own subclass of `ViewContext` and designate an instance of this custom class as your "exposed" target, via  `view_context_class`method.
+You can also have the exposed methods automatically cache the result in an instance variable, by using the `expose_cached` variant.
+
+```ruby
+class PostsController < ActionController::Base
+  include ContextExposer::BaseController
+  
+  expose_cached(:post)  { Post.find params[:id] }
+  expose_cached(:posts) { Post.find params[:id] }
+end
+```
+
+This is especially useful if used in combination with `decorates_before_rendering`, which only works on cached objects.
+
+## Macros
+
+You can also choose to use the class macros made available on `ActionController::Base` as Rails loads.
+
+Use `:base` or `resource` or your custom extension to include the ContextExposer controller module of your choice. The macro `context_exposer :base` is equivalent to writing `include ContextExposer::BaseController`
+
+```ruby
+class PostsController < ActionController::Base
+  context_exposer :base
+```
+
+## Sublclassing and customizing the ViewContext
+
+You can also define your own subclass of `ViewContext` and designate an instance of this custom class as your "exposed" target, via  `view_ctx_class`method.
+You can also override the class method of the same name for custom class name construction behavior ;)
 
 Example:
 
@@ -52,10 +89,16 @@ Example:
 class PostsController < ActionController::Base
   include ContextExposer::BaseController
   
-  view_context_class :posts_view_context
+  view_ctx_class :posts_view_context
 
-  exposed(:post)  { Post.find params[:id] }
-  exposed(:posts) { Post.all }
+  # One model instance
+  exposed(:post)        { Post.find params[:id] } 
+
+  # Relation (for further scoping or lazy load)
+  exposed(:posts)       { Post.all } 
+
+  # Array of model instances
+  exposed(:posts_list)  { Post.all.to_a } 
 end
 ```
 
@@ -90,7 +133,7 @@ HAML view example
 
 ```haml
 %h1 Admin Posts
-= context.admin_posts.each do |post|
+= ctx.admin_posts.each do |post|
   %h2 = post.name
 ```
 
@@ -101,17 +144,26 @@ This approach opens up many new exciting ways to slice and dice your logic in a
 
 ### ResourceController
 
-The `ResourceController` automatically sets up the typical singular and plural-form resource helpers.
+The `ResourceController` automatically sets up the typical singular and plural-form resource helpers. For example for PostsController:
+
+* `post` - one Post instance
+* `posts` - Search Relatation (for lazy load or further scoping)
+* `posts_list` - Array of Post instances
 
 This simplifies the above `PostsController` example to this:
 
 ```ruby
 class PostsController < ActionController::Base
+  # alternatively: context_exposer :resource
   include ContextExposer::ResourceController
+
+  expose_resources :all
 end
 ```
 
-`ResourceController`  uses the following internal logic for its default functionality. You can override these methods to customize your behavior as needed.
+The macro `expose_resources` optionally takes a list of the types of resource you want to expose. Valid types are `:one`, `:many` and `:list` respectively (for fx: `post`, `posts` and `posts_list`).
+
+`ContextExposer::ResourceController`  uses the following internal logic for its default functionality. You can override these methods to customize your behavior as needed.
 
 ```ruby
 module ContextExposer::ResourceController
@@ -132,22 +184,75 @@ module ContextExposer::ResourceController
   end
 ```
 
-## Integration with decent_exposure gem
+Tip: You can create reusable module and then include your custom ResourceController.
+
+```ruby
+module NamedResourceController
+  extend ActiveSupport::Concern
+  include ContextExposer::ResourceController
+
+  protected
+
+  def resource_id
+    params[:name]
+  end
+end
+```
+
+```ruby
+class PostsController < ActionController::Base
+  include NamedResourceController
+end
+
+Tip: If you put your module inside the `ContextExposer` namespace, you can even use the `context_exposer` macro ;)
+
+## Integrations with other exposure gems and patterns
+
+You can use the class macro `integrate_with(name)` to integrate with either:
+
+* decent_exposure - `integrate_with :decent_exposure`
+* decorates_before_rendering - `integrate_with :decorates_before`
+* instance vars - `integrate_with :instance_vars`
+
+Note: You can even integrate with multiple strategies
 
-Initial integration support is included for `decent_exposure`, another popular gem with similar functionality. To add methods exposed by `decent_exposure` `#expose` to the context object, simply call `#context_expose_decently` or the alias method `#expose_decently`.
+`integrate_with :decent_exposure, :instance_vars`
+
+You can also specify your integrations directly as part of your `context_exposer` call (recommended)
+
+`context_exposer :base, with: :decent_exposure`
+
+In case you use the usual (default) Rails pattern of passing instance variables, you can slowly migrate to exposing via `ctx` object, by adding a simple macro `context_expose :instance_vars` to your controller.
+
+For decorated instance variables (see `decorates_before_rendering` gem), similarly use `context_expose :decorated_instance_vars`.
+
+All of these `context_expose :xxxx` methods can optionally take an `:except` or `:only` option with a list of keys, similar to a `before_filter`.
+
+The method `context_expose :decorated_instance_vars` can additionally take a `:for`option of either `:collection` or `:non_collection` to limit the type of instance vars exposed.
+
+`context_expose` integration
+
+* :instance_vars
+* :decorated_instance_vars
+* :decently
+
+Here is a full example demonstrating integration with `decent_exposure`.
 
 ```ruby
 # using gem 'decent_exposure'
 # auto-included in ActionController::Base
 
 class PostsController < ActionController::Base
-  include ContextExposer::ResourceController
+  # make context_expose_decently method available
+  context_exposer :base, with :decent_exposure
 
-  expose(:posts)
-  expose(:post) { Post.first}
-  expose(:postal)
+  expose(:posts)  { Post.all.order(:created_at, :asc) }
+  expose(:post)   { Post.first}
+  expose(:postal) { '1234' }
 
-  context_expose_decently except: 'postal'
+  # mirror all methods exposed via #expose on #ctx object 
+  # except for 'postal' method
+  context_expose :decently except: 'postal'
 end
 ```
 
@@ -155,10 +260,75 @@ HAML view example
 
 ```haml
 %h1 Posts
-= context.posts.each do |post|
+= ctx.posts.each do |post|
   %h2 = post.name
 ```
 
+## Decorates before rendering
+
+A patch for the `decorates_before_render` gem is currently made available.
+
+`ContextExposer.patch :decorates_before_rendering`
+
+You typically use this in a Rails initializer. This way, `decorates_before_rendering` should try to decorate all your exposed variables before rendering, whether your view context is exposed as instance vars, methods or on the `ctx` object of the view ;)
+
+Note: You can now also use the macro `decorates_before_render` to include the `DecoratesBeforeRendering` module.
+
+### Auto-finding a decorator
+
+For the patched version of `decorates_before_render` to work, your exposed and cached object must either have a `model_name` method that returns the name of the model name to be used to calculate the decorator name to use, or alternatively (and with higher precedence if present), a `decorator` method that takes the controller (self) as an argument and returns the full name of the decorator to use ;)
+
+Example:
+
+```ruby
+class PostsController < ActionController::Base
+  decorates_before_render
+  context_exposer :base, with :decent_exposure
+
+  expose_cached(:first_post) { Post.first } 
+
+  protected
+
+  def admin?
+    @admin ||= current_user.admin?
+  end
+end
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  def decorator contrl
+    contrl.send(:admin?) ? 'Admin::PostDecorator' : model_name      
+  end
+end
+
+### Auto-detection Error handling
+
+If the auto-decoration can't find a decorator for an exposed variable (or method), it will either ignore it (not decorate it) or call `__handle_decorate_error_(error)` which by default will log a Rails warning. Override this error handler as it suits you.
+
+## Testing
+
+The tests have been written in rspec 2 and capybara. 
+The test suite consists of:
+
+* Full app tests
+* Units tests
+
+### Dummy app feature tests
+
+A Dummy app has been set up for use with Capybara feature testing.
+Please see: http://alindeman.github.com/2012/11/11/rspec-rails-and-capybara-2.0-what-you-need-to-know.html
+
+The feature tests can be found in `spec/app`
+
+`$ bundle exec rspec spec/context_exposer`
+
+### Unit tests (specs)
+
+The unit tests can be found in `spec/context_exposer`
+
+`$ bundle exec rspec spec/context_exposer`
+
 ## Contributing
 
 1. Fork it

data/lib/context_exposer.rb

@@ -1,9 +1,24 @@
 require "context_exposer/version"
 
 module ContextExposer
+  def self.patch name
+    case name.to_sym
+    when :decorates_before_rendering
+      require "context_exposer/patch/#{name}"
+    else
+      raise ArgumentError, "No patch defined for: #{name}. Try one of #{patches}"
+    end
+  end
+
+  def self.patches
+    [:decorates_before_rendering]
+  end
 end
 
 require "active_support"
 require "context_exposer/base_controller"
 require "context_exposer/resource_controller"
+require "context_exposer/cached_resource_controller"
 require "context_exposer/view_context"
+require "context_exposer/macros"
+require "context_exposer/rails_config"

data/lib/context_exposer/base_controller.rb

@@ -1,51 +1,51 @@
+require "context_exposer/integrations"
+
 module ContextExposer::BaseController
   extend ActiveSupport::Concern
+  include ContextExposer::Integrations::Base
 
   included do
-    before_filter :configure_exposed_context
-
-    expose_context :context
+    # before_filter :configure_exposed_context
+    set_callback :process_action, :before, :configure_exposed_context
 
-    # set_callback :process_action, :before, :configure_exposed_context
+    expose_context :ctx
   end
 
-  def view_context    
-    @view_context ||= build_view_context
+  def view_ctx
+    @view_ctx ||= build_view_ctx
   end
-  alias_method :context, :view_context
+  alias_method :ctx, :view_ctx
 
   module ClassMethods
-    def exposed name, &block
-      # puts "store: #{name} in hash storage for class #{self}"
-      exposure_storage[name.to_sym] = block
+    def exposed name, options = {}, &block
+      _exposure_storage[name.to_sym] = {options: options, proc: block}
     end
 
-    # expose all exposures exposed by decent_exposure to context
-    def context_expose_decently options = {}
-      transfer_keys = _exposures.keys
-      except = (options[:except] || {}).map(&:to_sym)
-      only = (options[:only] || {}).map(&:to_sym)
-
-      transfer_keys = transfer_keys - except
+    def expose_cached name, options = {}, &block
+      exposed name, options.merge(cached: true), &block
+    end
 
-      unless only.empty?
-        transfer_keys.select {|k| only.include? k.to_sym } 
+    def view_ctx_class name
+      define_method :view_ctx_class do
+        @view_ctx_class ||= name.kind_of?(Class) ? name : name.to_s.camelize.constantize
       end
+    end
 
-      transfer_keys.each do |exposure|
-        exposed exposure do
-          send(exposure)
-        end
+    def integrate_with *names
+      names.flatten.compact.each do |name|
+        self.send :include, "ContextExposer::Integrations::With#{name.to_s.camelize}".constantize
       end
     end
-    alias_method :expose_decently, :context_expose_decently 
+    alias_method :integrates_with, :integrate_with
 
-    def view_context_class name
-      define_method :view_context_class do
-        @view_context_class ||= name.kind_of?(Class) ? name : name.to_s.camelize.constantize
-      end
+    def context_expose name, options = {}
+      send "context_expose_#{name}", options
     end
 
+    def _exposure_storage
+      _exposure_hash[self.to_s] ||= {}
+    end    
+
     protected
 
     def expose_context name
@@ -59,32 +59,26 @@ module ContextExposer::BaseController
       end    
       helper_method name
       hide_action name
-      @exposed_view_context = true
+      @_exposed_view_context = true
     end
 
     def exposed_view_context?
-      @exposed_view_context == true
+      @_exposed_view_context == true
     end
 
-    def exposure_storage
-      exposure_hash[self.to_s] ||= {}
-    end
-
-    def exposure_hash
-      @exposure_hash ||= {}
-    end
+    def _exposure_hash
+      @_exposure_hash ||= {}
+    end    
   end
 
   # must be called after Controller is instantiated
   def configure_exposed_context
     return if configured_exposed_context?
     clazz = self.class
-    exposed_methods = clazz.send(:exposure_hash)[clazz.to_s] || []
-    exposed_methods.each do |name, procedure|
-      this = self
-      view_context.send :define_singleton_method, name do 
-        this.instance_eval(&procedure)
-      end
+    exposed_methods = clazz.send(:_exposure_hash)[clazz.to_s] || []
+    exposed_methods.each do |name, obj|
+      options = obj[:options] || {}
+      options[:cached] ? _add_cached_ctx_method(obj, name) : _add_ctx_method(obj, name)
     end
     @configured_exposed_context = true
   end
@@ -95,13 +89,39 @@ module ContextExposer::BaseController
 
   protected
 
+  def _add_ctx_method obj, name
+    this = self    
+    proc = obj[:proc]
+    inst_var_name = "@#{name}"
+
+    view_ctx.send :define_singleton_method, name do
+      this.instance_eval(&proc)
+    end
+  end
+
+  def _add_cached_ctx_method obj, name
+    this = self
+    options = obj[:options]
+    proc = obj[:proc]
+    inst_var_name = "@#{name}"
+
+    view_ctx.send :define_singleton_method, name do
+      old_val = instance_variable_get inst_var_name
+      return old_val if old_val
+
+      val = this.instance_eval(&proc)
+      instance_variable_set inst_var_name, val
+      val
+    end
+  end
+
   # returns a ViewContext object 
   # view helpers can be exposed as singleton methods, dynamically be attached (see below)
-  def build_view_context
-    view_context_class.new self
+  def build_view_ctx
+    view_ctx_class.new self
   end
 
-  def view_context_class
-    @view_context_class ||= ContextExposer::ViewContext
+  def view_ctx_class
+    @view_ctx_class ||= ContextExposer::ViewContext
   end
 end