h1. CanTango CanTango is an advanced Access Control (permissions) system for Rails 3. It: * extends "CanCan":http://github.com/ryanb/cancan and offers a more granular Object Oriented design * integrates with _role_ and _authentication_ systems in a non-intrusive manner * can _cache_ ability rules between requests for increased performance * allows for context specific "Permits":https://github.com/kristianmandrup/cantango/wiki/Permits with rules * supports multiple "Devise":https://github.com/plataformatec/devise users/accounts * can _store_ static ability rules in a permission store for easy administration * manage the permission store from a web UI using the "cantango_editor":https://github.com/stanislaw/cantango_editor, a mountable Rails engine h3. Will CanTango meet my Access Control (permission) requirements? * "CanCan vs CanTango":https://github.com/kristianmandrup/cantango/wiki/CanCan-vs-CanTango * "CanTango overview":https://github.com/kristianmandrup/cantango/wiki h2. Installation h3. Ruby versions CanTango has been tested to work with _Ruby 1.9+_ and currently doesn't support _Ruby 1.8.7_ If you require ruby 1.8.7 support, please help patch it and make a pull request ;) h3. Install in current environment (or gemset) @gem install cantango@ h3. Install in application Insert into Gemfile @gem 'cantango'@ Run bundler in a terminal/console from the folder of your Gemfile (root folder of app) @$ bundle@ h2. Update Nov 21, 2011 Version 0.9.4.6 has been released. Fixes bug in configuration/permit_registry. The "wiki":https://github.com/kristianmandrup/cantango/wiki has been rewritten and updated to reflect all latest design changes and feature additions. I am now in the process of a major refactoring effort in the *major-refactor* branch. I've split up cantango into separate gems which will be developed independently in the future (towards a 1.0 release), notably one gem for each engine. I might rename the "engine" concept into "component" so that developers don't confuse it with Rails engines ;) * "cantango-cache":https://github.com/kristianmandrup/cantango-cache * "permits":https://github.com/kristianmandrup/permits * "permit_store":https://github.com/kristianmandrup/permit_store I might also extract the _permission_ engine (currently known as _user_ac_). Lot's of changes coming doewn the pipeline. Please help make CanTango much better and more stable! Thanks! h2. Quickstart See the "Quickstart guide":https://github.com/kristianmandrup/cantango/wiki/Quickstart in the wiki. For devise integration, see "Quickstart with Devise":https://github.com/kristianmandrup/cantango/wiki/Quickstart-cantango-with-devise The following scenarios demonstrate some of the problems CanTango can help solve in an elegant way * "Simple scenario":https://github.com/kristianmandrup/cantango/wiki/Simple-scenario * "Complex scenario":https://github.com/kristianmandrup/cantango/wiki/Complex-scenario h3. Generators Cantango comes with a set of "Generators":https://github.com/kristianmandrup/cantango/wiki/Generators to get your app dancing... Simply start with: * cantango:install To use the Permit generators please see the "Generators":https://github.com/kristianmandrup/cantango/wiki/Generators page ;) h3. Rails 3 configuration The CanTango "Configuration":https://github.com/kristianmandrup/cantango/wiki/Configuration consists of a nice DSL that let's you configure most of the things we imagine you would want to customize. Feel free to suggest more configuration options! h3. Abilities via Permits and Permissions Abilities are Access Control rules. With CanTango, the AC rules can be defined in both: * "Permissions":https://github.com/kristianmandrup/cantango/wiki/Permissions (fx a yaml file) * "Permits":https://github.com/kristianmandrup/cantango/wiki/Permits (special classes) Note: For the simplest cases, you can define a @#permit_rules@ instance method directly in _CanTango::Ability_ Abilities can be defined for the following conceptual entities: * User models * User Account models * Roles * Role groups * Users You can even create your own Permit types to suit your own needs! This feature will be further improved in the upcoming 1.0 release. h3. Design overview The default CanTango Ability pattern is simple. 1. Return cached ability rules for candidate if available (and cache is on) 2. Generate rules for candidate 3. Cache rules for candidate (if cache is on) An ability candidate is typically either a user or an account instance. Caching can be enabled or disabled. To generate the rules, one or more engines are executed. CanTango comes with the following engines: * "Permit engine"::https://github.com/kristianmandrup/cantango/wiki/Permit-engine * "Permission engine":https://github.com/kristianmandrup/cantango/wiki/Permission-engine You can however freely plugin or unplug engines as you wish as described in "Engines":https://github.com/kristianmandrup/cantango/wiki/Engines h3. Dependencies, Adapters and Loading CanTango had been designed to be minimally intrusive and not require too many external dependencies. If you want to enable Moneta for caching or storage, you must execute an adapter macro: @CanTango.adapter :moneta@ This will setup lazy-loading of Moneta cache and Moneta store respectively. If you want to enable compilation of dynamic rules (using blocks) you must use the @:compiler@ adapter If you use any of these adapters, you must manually include the following in your Rails app Gemfile. @gem 'dkastner-moneta'@ for moneta adapter and @gem 'sourcify'@ for the compiler adapter. CanTango uses @autoload_modules@ from the "sweetloader":https://github.com/kristianmandrup/sweet_loader.git gem. This ensures that all such modules are lazy-loaded. Thus if you configure CanTango to exclude an engine, the code for that engine will never be loaded, minimizing the load time and memory print. h2. You need help? Please post ideas, questions etc. in the "cantango group":http://groups.google.com/group/cantango on Google. h3. Bugs, issues or feature request/ideas? If you encounter bugs, raise an issue or: * Fork the project. * Make your feature addition or bug fix. * Add tests for it. This is important so I don't break it in a future version unintentionally. * Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull) * Send me a pull request. Bonus points for topic branches. h2. Contributors * Kristian Mandrup * "Stanislaw Pankevich":https://github.com/stanislaw h3. Copyright Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.