restful_acl 3.0.3 → 3.0.4

data/README.markdown

@@ -0,0 +1,160 @@
+RESTful_ACL
+===========
+RESTful_ACL is a full-stack context-based permission engine. It provides access control that is contextually aware. (If a parent is closed, a child is not editable, etc.) Permission is as simple as true or false.
+
+Requirements
+------------
+RESTful_ACL requires the notion of a `current_user`. Most authenticaion plugins provide this (AuthLogic, RESTful_Authentication, etc.)
+
+How to Install
+--------------
+Install the RESTful_ACL gem:
+<pre><code>sudo gem install restful_acl -s http://gemcutter.org</code></pre>
+
+Add the gem to your environment.rb file as thus:
+<pre><code>config.gem "restful_acl"</code></pre>
+
+RESTful_ACL requires a named route named "denied". Add the following to your routes.rb file:
+<pre><code>map.denied 'denied', :controller => 'some_controller', :action => 'denied_action'</code></pre>
+
+Controllers
+-----------
+Add `before_filter :has_permission?` into any controller that you'd like to restrict access to (or `application_controller.rb` for your entire app).
+
+Models
+------
+Define the following five methods in the model of every resource you'd like to restrict access to. The five methods can contain anything you'd like so long as they return a boolean true or false. This allows you to define your User's roles any way you wish.
+
+<pre><code>class Issue < ActiveRecord::Base
+
+  # This method checks permissions for the :index action
+  def self.is_indexable_by(user, parent = nil)
+  end
+
+  # This method checks permissions for the :create and :new action
+  def self.is_creatable_by(user, parent = nil)
+  end
+
+  # This method checks permissions for the :show action
+  def is_readable_by(user, parent = nil)
+  end
+
+  # This method checks permissions for the :update and :edit action
+  def is_updatable_by(user, parent = nil)
+  end
+
+  # This method checks permissions for the :destroy action
+  def is_deletable_by(user, parent = nil)
+  end
+
+end
+</code></pre>
+
+Parent / Child resources
+------------------------
+
+Sometimes actions should only be allowable on a resource if some "parent" resource allows them. Contextual permissions FTW.
+
+Link your "child" resource with its "parent" resource by using the `logical_parent` macro and you'll have access to the "parent" resource in your child's RESTful_ACL methods.
+
+<pre><code>class Child < ActiveRecord::Base
+  logical_parent :parent
+  ...
+end
+</code></pre>
+
+If the "child" resource is a singleton, just pass `:singleton` to the `logical_parent` macro:
+
+<pre><code>class Car < ActiveRecord::Base
+  logical_parent :owner, :singleton
+  ...
+end
+</code></pre>
+
+View Helper
+-----------
+
+RESTful_ACL adds a view helper called `allowed?`. Simply pass this method a block containing the URL you'd like to check permission on and it will do the rest.
+The link will appear if the `current_user` is allowed to access the passed-in link's action.
+
+<pre><code>= allowed?{ link_to ‘Foo Index’, foos_path }
+= allowed?{ link_to 'Edit Foo', edit_foo_path(@foo) }
+= allowed?{ link_to 'Create Foo', new_foo_path }
+= allowed?{ link_to 'View Foo', foo_path(@foo) }
+= allowed?{ link_to 'Delete Foo', foo_path(@foo), :method => :delete }
+</code></pre>
+
+
+Huh? Here's an example
+----------------------
+Let's say that you have two resources: `Project` and `Issue`. A Project has many Issues, an Issue belongs to a Project. I'd like to make sure that the current user is a member of the Project before they can create a new Issue in that Project:
+
+<pre><code>class Issue < ActiveRecord::Base
+  logical_parent :project
+
+  belongs_to :author
+  belongs_to :project
+
+  def self.is_indexable_by(user, parent = nil)
+    user.projects.include?(parent)
+  end
+
+  def self.is_creatable_by(user, parent = nil)
+    user.projects.include?(parent)
+  end
+
+  def is_updatable_by(user, parent = nil)
+    user == author && parent.is_active?
+  end
+
+  def is_deletable_by(user, parent = nil)
+    user == author
+  end
+
+  def is_readable_by(user, parent = nil)
+    user.projects.include?(parent)
+  end
+end
+</code></pre>
+
+If you still have questions, please checkout the [test app](http://github.com/mdarby/restful_acl_app)
+
+Admins RULE!
+------------
+RESTful_ACL grants global access to all actions to site administrators. To enable this, make sure that your User model defines an `is_admin?` method *and/or* an `is_admin` attribute. If the `current_user.is_admin?` returns true, access will be granted automatically.
+
+How to Test
+-----------
+I normally do something along these lines in RSpec:
+
+<pre><code>describe "Issue" do
+  before do
+    @project = mock_model(:project)
+    @author  = mock_model(:user, :projects => [@project])
+    @issue   = Factory(:issue, :author => @author, :project => @project)
+  end
+
+  it "should be modifiable by the author when the Project is active" do
+    @project.stub!(:is_active? => true)
+    @issue.is_updatable_by(@author, @project).should be_true
+  end
+
+  it "should be deletable by the author" do
+    @issue.is_deletable_by(@author, @project).should be_true
+  end
+
+  it "should be readable by those assigned to the Project" do
+    Issue.is_readable_by(@author, @project).should be_true
+  end
+
+  it "should be creatable by those assigned to the Project" do
+    Issue.is_creatable_by(@author, @project).should be_true
+  end
+end
+</code></pre>
+
+About the Author
+----------------
+My name is [Matt Darby.](http://blog.matt-darby.com) I’m an IT Manager and pro-web-dev at for [Dynamix Engineering](http://dynamix-ltd.com) and hold a Master’s Degree in Computer Science from [Franklin University](http://www.franklin.edu) in sunny [Columbus, OH.](http://en.wikipedia.org/wiki/Columbus,_Ohio)
+
+Feel free to check out my [site](http://matt-darby.com) or [recommend me](http://www.workingwithrails.com/person/10908-matt-darby)

data/VERSION

@@ -1 +1 @@
-3.0.3
+3.0.4

data/lib/restful_acl.rb

@@ -4,4 +4,5 @@ require 'restful_acl/base'
 require 'restful_acl/controller'
 require 'restful_acl/helper'
 require 'restful_acl/model'
-require 'restful_acl/errors'
+require 'restful_acl/errors'
+require 'ostruct'

data/lib/restful_acl/helper.rb

@@ -17,6 +17,8 @@ module RestfulAcl
           *****************************************************************************************
 
         STR
+        
+        false
       end
     end
 

data/restful_acl.gemspec

@@ -5,20 +5,20 @@
 
 Gem::Specification.new do |s|
   s.name = %q{restful_acl}
-  s.version = "3.0.3"
+  s.version = "3.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matt Darby"]
-  s.date = %q{2009-12-08}
+  s.date = %q{2010-01-24}
   s.description = %q{A Ruby on Rails plugin that provides fine grained access control to RESTful resources.}
   s.email = %q{matt@matt-darby.com}
   s.extra_rdoc_files = [
-    "README.textile"
+    "README.markdown"
   ]
   s.files = [
     ".gitignore",
      "MIT-LICENSE",
-     "README.textile",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "init.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: restful_acl
 version: !ruby/object:Gem::Version 
-  version: 3.0.3
+  version: 3.0.4
 platform: ruby
 authors: 
 - Matt Darby
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-08 00:00:00 -05:00
+date: 2010-01-24 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,11 +29,11 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README.textile
+- README.markdown
 files: 
 - .gitignore
 - MIT-LICENSE
-- README.textile
+- README.markdown
 - Rakefile
 - VERSION
 - init.rb

data/README.textile

@@ -1,162 +0,0 @@
-h1. Major changes in 3.0 release!
-
-* RESTful_ACL has been completely refactored for speed and usability.
-* A full Cucumber test suite has been written (http://github.com/mdarby/restful_acl_app).
-* The view helpers @creatable@, @deletable@, @updatable@, @readable@ have been replaced by @allowed?@ (see below for more details).
-
-h2. RESTful_ACL
-
-RESTful_ACL is rails gem that provides a full stack, contextual access control to RESTful resources. Authorization is as simple as true or false.
-
-h3. What it does
-
-RESTful_ACL is a context-based permission engine. It provides full stack access control that is resource context aware. (If a parent is closed, a child is not editable, etc.)
-
-h3. Requirements
-
-RESTful_ACL requires the notion of a @current_user@. Most authenticaion plugins provide this (AuthLogic, RESTful_Authentication, etc.)
-
-h3. How to Install
-
-Install the RESTful_ACL gem:
-<pre>sudo gem install restful_acl -s http://gemcutter.org</pre>
-
-Add the gem to your environment.rb file as thus:
-<pre>config.gem "restful_acl"</pre>
-
-RESTful_ACL requires a named route named "denied". Add the following to your routes.rb file:
-<pre>map.denied 'denied', :controller => 'some_controller', :action => 'denied_action'</pre>
-
-h3. How to Use
-
-h4. Controllers
-
-Add @before_filter :has_permission?@ into any controller that you'd like to restrict access to (or application_controller.rb for your entire app).
-
-h4. Models
-
-Define a parent resource (if one exists) by using the @logical_parent@ method, and define the following five methods in the model of every resource you'd like to restrict access to. The five methods can contain anything you'd like so long as they return a boolean true or false. This allows you to define your User's roles any way you wish.
-
-<pre>
-  class Issue < ActiveRecord::Base
-    logical_parent :some_model_name
-
-    # This method checks permissions for the :index action
-    def self.is_indexable_by(user, parent = nil)
-    end
-
-    # This method checks permissions for the :create and :new action
-    def self.is_creatable_by(user, parent = nil)
-    end
-
-    # This method checks permissions for the :show action
-    def is_readable_by(user, parent = nil)
-    end
-
-    # This method checks permissions for the :update and :edit action
-    def is_updatable_by(user, parent = nil)
-    end
-
-    # This method checks permissions for the :destroy action
-    def is_deletable_by(user, parent = nil)
-    end
-  end
-</pre>
-
-h4. Singleton Resources
-
-RESTful_ACL 2.1+ supports singleton resources. Just pass @:singleton@ to the @logical_parent@
-
-<pre>
-  class Car < ActiveRecord::Base
-    logical_parent :owner, :singleton
-    ...
-  end
-</pre>
-
-h4. View Helper
-
-RESTful_ACL provides you with a view helper named @allowed?@. Simply pass this method a block containing the URL you'd like to check permission on and it will do the rest.
-If the @current_user@ is allowed to access the requested link's action, the link will appear; otherwise no link will show.
-<pre>= allowed?{ link_to ‘Foo Index’, foos_path }
-= allowed?{ link_to 'Edit Foo', edit_foo_path(@foo) }
-= allowed?{ link_to 'Create Foo', new_foo_path }
-= allowed?{ link_to 'View Foo', foo_path(@foo) }
-= allowed?{ link_to 'Delete Foo', foo_path(@foo), :method => :delete }</pre>
-
-h3. Huh? Here's an example
-
-Let's say that you have two resources: Project and Issue. A Project has many Issues, an Issue belongs to a Project. I'd like to make sure that the current user is a member of the Project before they can create a new Issue in that Project:
-
-<pre>
-  class Issue < ActiveRecord::Base
-    logical_parent :project
-
-    belongs_to :author
-    belongs_to :project
-
-    def self.is_indexable_by(user, parent = nil)
-      user.projects.include?(parent)
-    end
-
-    def self.is_creatable_by(user, parent = nil)
-      user.projects.include?(parent)
-    end
-
-    def is_updatable_by(user, parent = nil)
-      user == author && parent.is_active?
-    end
-
-    def is_deletable_by(user, parent = nil)
-      user == author
-    end
-
-    def is_readable_by(user, parent = nil)
-      user.projects.include?(parent)
-    end
-  end
-</pre>
-
-h3. Admins RULE!
-
-RESTful_ACL grants global access to all actions to site administrators. To enable this, make sure that your User model defines an @is_admin?@ method *and/or* an @is_admin@ attribute. If the @current_user.is_admin?@ returns true, access will be granted automatically.
-
-h3. How to Test
-
-I normally do something along these lines in RSpec:
-<pre>
-  describe "Issue" do
-    before do
-      @project = mock_model(Project)
-      @author  = mock_model(User, :projects => [@project])
-      @issue = Issue.factory_girl(:issue, :author => @author, :project => @project)
-    end
-
-    it "should be modifiable by the author when the Project is active" do
-      @project.stub!(:is_active? => true)
-      @issue.is_updatable_by(@author, @project).should be_true
-    end
-
-    it "should be deletable by the author" do
-      @issue.is_deletable_by(@author, @project).should be_true
-    end
-
-    it "should be readable by those assigned to the Project" do
-      Issue.is_readable_by(@author, @project).should be_true
-    end
-
-    it "should be creatable by those assigned to the Project" do
-      Issue.is_creatable_by(@author, @project).should be_true
-    end
-  end
-</pre>
-
-h3. Help
-
-Add a ticket to "RESTful_ACL's Lighthouse Account":http://mdarby.lighthouseapp.com/projects/28698-restful_acl/overview
-
-h3. About the Author
-
-My name is "Matt Darby.":http://blog.matt-darby.com I’m an IT Manager and pro-web-dev at for "Dynamix Engineering":http://dynamix-ltd.com and hold a Master’s Degree in Computer Science from "Franklin University":http://www.franklin.edu in sunny "Columbus, OH.":http://en.wikipedia.org/wiki/Columbus,_Ohio
-
-Feel free to check out my "site":http://matt-darby.com or "recommend me":http://www.workingwithrails.com/person/10908-matt-darby