Permalink
Browse files

Add rationale and disclaimer to README.

  • Loading branch information...
1 parent 8b3a15a commit d30c0cba09a3e59c20fa25ab1a003c74ca47e28d James Hunt & Paul Mucur committed with mudge Mar 31, 2012
Showing with 46 additions and 5 deletions.
  1. +44 −2 README.md
  2. +1 −1 proffer.gemspec
  3. +1 −2 spec/proffer_integration_spec.rb
View
@@ -2,12 +2,34 @@ Proffer [![Build Status](https://secure.travis-ci.org/hudge/proffer.png?branch=m
=======
A module to stop Action Controller from copying every instance variable available
-to an action to the view by default. Instead, use an explicit API to expose
-variables as local variables within views.
+to an action to the view by default. Instead, Proffer provides a way to explicitly
+expose values as local variables within views.
+
+Rationale
+---------
+
+By default, Action Controller will make any instance variables present during an
+action available to its views (including partials). This effectively makes them
+global variables and can obscure their origin when maintaining views. Partials
+that exploit this behaviour can be particularly difficult to maintain as they
+may inherit state from their caller implicitly.
+
+We want to see if removing this default behaviour changes the way views are
+written. By forcing explicit declaration of dependencies, will better, more
+encapsulated design result?
Usage
-----
+Add the following to your `Gemfile`:
+
+```ruby
+gem 'proffer'
+```
+
+Include the `Proffer` module into any controllers you wish (include into
+`ApplicationController` to enforce this behaviour throughout your application):
+
```ruby
class PostsController < ApplicationController
include Proffer
@@ -21,9 +43,29 @@ class PostsController < ApplicationController
end
```
+Any proffered values will then be available to your views by their key:
+
```erb
<%= form_for(post) do |f| %>
...
<% end %>
```
+Compatibility
+-------------
+
+As we rely on `ActionController#view_assigns`, this will only work with versions
+of Rails 3.0 or later. It is currently tested against Rails 3.2.
+
+Disclaimer
+----------
+
+We have not yet tried this in production so proceed with caution. This gem
+overrides `ActionController#view_assigns` and extends `ActionController#render`,
+so it may be incompatible with other gems that override these methods.
+
+License
+-------
+
+See LICENSE.txt
+
View
@@ -1,7 +1,7 @@
Gem::Specification.new do |s|
s.name = "proffer"
s.summary = "An Action Controller module to hide instance variables from views by default."
- s.description = "A module to stop Action Controller from copying every instance variable available to an action to the view by default. Instead, use an explicit API to expose variables as local variables within views."
+ s.description = "A module to stop Action Controller from copying every instance variable available to an action to the view by default. Instead, Proffer provides a way to explicitly expose values as local variables within views."
s.version = "0.9.0"
s.authors = ["James Hunt", "Paul Mucur"]
s.homepage = "http://github.com/hudge/proffer"
@@ -1,6 +1,7 @@
require 'spec_helper_rails'
class ApplicationController < ActionController::Base
+ include Proffer
end
describe ApplicationController, :type => :controller do
@@ -9,8 +10,6 @@ class ApplicationController < ActionController::Base
controller do
self.view_paths = [File.expand_path('../fixtures', __FILE__)]
- include Proffer
-
def index
@foo = "Not passed through"
proffer :my_nice_variable => "Woooo"

0 comments on commit d30c0cb

Please sign in to comment.