README.md in action_policy-0.0.1 vs README.md in action_policy-0.1.0
- old
+ new
@@ -1,39 +1,98 @@
+[](https://badge.fury.io/rb/action_policy)
+[](https://travis-ci.org/palkan/action_policy)
+[](http://actionpolicy.evilmartians.io)
+
# ActionPolicy
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/action_policy`. To experiment with that code, run `bin/console` for an interactive prompt.
+Action Policy is an authorization framework for Ruby and Rails applications.
-TODO: Delete this and the text above, and describe your gem
+📑 [Documentation][]
+<a href="https://evilmartians.com/?utm_source=action_policy">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
## Installation
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
```ruby
-gem 'action_policy'
+gem "action_policy"
```
And then execute:
$ bundle
-Or install it yourself as:
+## Usage
- $ gem install action_policy
+Action Policy relies on resource-specific policy classes (just like [Pundit](https://github.com/varvet/pundit)).
-## Usage
+First, add an application-specific `ApplicationPolicy` with some global configuration to inherit from:
-TODO: Write usage instructions here
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+end
+```
-## Development
+Then write a policy for a resource. For example:
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+class PostPolicy < ApplicationPolicy
+ # everyone can see any post
+ def show?
+ true
+ end
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+ def update?
+ # `user` is a performing subject,
+ # `record` is a target object (post we want to update)
+ user.admin? || (user.id == record.user_id)
+ end
+end
+```
+Now you can easily add authorization to your Rails\* controller:
+
+```ruby
+class PostsController < ApplicationController
+ def update
+ @post = Post.find(params[:id])
+ authorize! @post
+
+ if @post.update(post_params)
+ redirect_to @post
+ else
+ render :edit
+ end
+ end
+end
+```
+
+\* See [Non-Rails Usage](docs/non_rails.md) on how to add `authorize!` to any Ruby project.
+
+
+When authorization is successful (i.e., the corresponding rule returns `true`), nothing happens, but in case of authorization failure `ActionPolicy::Unauthorized` error is raised.
+
+There is also an `allowed_to?` method which returns `true` or `false`, and could be used, in views, for example:
+
+```erb
+<% @posts.each do |post| %>
+ <li><%= post.title %>
+ <% if allowed_to?(:edit?, post) %>
+ = link_to post, "Edit"
+ <% end %>
+ </li>
+<% end %>
+```
+
+Read more in our [Documentation][].
+
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_policy.
+Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/action_policy.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[Documentation]: http://actionpolicy.evilmartians.io