Configuration

CanTango comes with a very advanced configuration DSL, that is nested in nature, using block constructs as you will see. For a Rails app, we recommend that you use the cantango.rb initializer for your configuration. Note: In the next release, we will include hooks to add configuration at certain trigger points in the application initialization for even more flexibility.

$RAILS/config/initializers/cantango.rb

The following list the main components that can be configured in CanTango:

• Ability
• Execution Modes
• Factory methods
• Adapters
• Autoload
• Categories
• Debug
• Engines
• Modes
• Guest
• Models
• Modes
• Permits
• Role groups
• Roles
• User
• User Account
• User Accounts
• Users

More configuration options can be found if you look into spec/cantango/configuration. We continue to add more configuration options as the new requirements demand it.

Ability config

The CanTango Ability can be configured with execution modes and factory methods.

Ability modes

The valid ability execution modes are: :cache, :no_cache, :both

CanTango.config.ability.mode = :cache

The mode :both will first run in :cache mode and add the cached rules and then run in :no_cache mode and add the non-cached rules to the final resulting rule set.

Ability Factory

Currently, the default CanTango Ability class is CanTango::AbilityExecutor. You can subclass this for your specific requirements.

class Custom::Ability < CanTango::AbilityExecutor
  def initialize candidate, options
  end
  ...
end

Now let CanTango know to use this class

CanTango.config.ability.factory.default_class = Custom::Ability

In rare cases, you might even want to define the factory method for how to construct this ability executor:

CanTango.config.ability do |ability|
  ability.mode = :cache
  ability.factory lambda {|candidate, options| CustomFactory.create_ability candidate, options } 
end

Adapters

Cantango comes with the following adapters

• moneta
• compiler

Enable use of moneta (for use with cache or rules store) via moneta gem.

CanTango.config.adapters.adapter :moneta

Enable compiler. This will enable cache to cache dynamic rules in the form of Procs that are converted to source code via the sourcify gem. You must add gem 'sourcify' to your Gemfile.

CanTango.config.adapters.adapter :compiler

Autoload

Autoload is :on by default for both models and permits. You can configure whether to autoload models and permits in the Rails app initialization process.

Autoloading models can be a problem sometimes, since some of your models might have class level dependencies which haven't been defined when the model is loaded. In these cases, turn off autoloading of models.

CanTango.config do |config|
  config.autoload.clear!
  config.autoload.models :off
  config.autoload.permits :on
end

Categories

You can register categories directly, instead of putting them all in the categories.yml repository. This is very useful when you want to generate the categories runtime.

categories = {:grains => ['Wheat', 'Barley'], 'genders' => ['Man', 'Woman']}
CanTango.config.categories.register categories

Debug

Debug can be turned on or off. In the future we will enable debug configuration at a more fine-grained level, fx for each individual engine and perhaps with different debug levels. Here some examples of configuring debug mode.

CanTango.config do |config|
  config.debug!
  config.debug.set :off
  config.debug.on?
end

CanTango.debug! # turn on
CanTango.debug? # is debug turned on?

Enable defaults

To enable default configuration settings:

CanTango.config.enable_defaults!

Currently it sets the engines on/off setting to their default and turns the :compiler adapter on.

Engines

CanTango has a concept of engines that can be mounted and configured, just like Rails 3. Don't confuse these two engine concepts are they are not in any way related or compatible! You can use the block construct to configure an individual engine as shown below.

CanTango.config do |config|
  config.engine(:permit) do |engine|
    engine.set :on
    engine.mode = :cache
  end
end

The built-in engine names are: :permit, :permission, :user_ac and :cache. The engine names might change as we approach the 1.0 release of CanTango. We recommend that you use #engine(name) to get the engine you want to configure.

Engines turned on/off

The Permits engine is :on by default. You can configure which engines are turned :on or :off.

CanTango.config do |config|
  config.engines.clear! # will set all engines to default setting on/off
  config.engines.all :on # turn on all engines

  # individual engine config
  config.engine(:permit).reset! # will set permits engine to default setting
  config.engine(:permission).set :on
  config.cache.set :on
end

Guest

Guest user example

CanTango.config.guest.user Proc.new { Guest.new } 

Guest account example

CanTango.config.guest.account Proc.new { Account.create :guest } 

Hooks

You can register hooks to take effect at certain point in the application initialization process. The current hooks are: :to_prepare, :after_initialize.

CanTango.config.register_hook :to_prepare, lambda { 
  CanTango.config.permits.register_class AdminUserPermit 
}

Localhost list

Register which hosts are local.

CanTango.config.localhost_list
CanTango.config.add_localhosts 'my.local.host', '10.19.342.13'

The local host list is used in case you use the #localhost? method inside a Permit. This will check the request.host against this list.

Models

Filter out models from REST helper method generation

CanTango.config.models.exclude :admin_users, :admin_comments

Permits

Permits can be configured both at the:

• type level
• individual permit level

Permit types enabled

CanTango.config do |config|
  config.permits.disable :role_groups, :special
  config.permits.enabled
  config.permits.available
end

The built-in permit types are: :user_type, :account_type, :roles, :role_groups, :special The special permits are the SystemPermit and AnyPermit

Permits enabled/disabled

You can also configure exactly which permits are enabled and disabled for each type of permit

CanTango.config do |config|
  config.permits.disable_for :role_groups, :admins, :bloggers
  config.permits.enable_all_for :roles
end

REST helper methods views/controllers

CanTango.config.enable_helpers :rest

This will enable and add the REST helper methods to Views and Controllers.

Roles and Role groups configuration

You can specify a subset of roles and/or role groups to include/exclude from CanTango with the methods #exclude and #only.

CanTango.config do |config|
  config.roles do |roles|
    roles.clear! # set roles settings back to default
    roles.exclude :admin, :editor
    roles.list_method = :roles
    roles.has_method = :role?
  end
  config.role_groups.only :publishers
end

This is especially useful for testing and debug purposes when you have many roles and role groups in play! Note that here we also specify the list and has methods for roles to override the defaults.

User

CanTango.config.user do |user|
  user.clear! # set user settings back to default
  user.unique_key_field = :username
  user.relations = user.default_relations + [:manager, :member]
  user.base_class = AppUser
end

Unique key field

This is used to caching purposes and for User permissions, where each user is identified by a unique key. By default this is set to :email.

Base class

This is used to set the base User model class. By default this is set to User. This setting is used when trying to create a Guest user. If no Guest factory is defined, CanTango will then try to call the #guest class method on this base class if such a model/class exists.

User relations

Note that the symbols in user.relations determines which Relations DSL methods will be available for Permits and Permissions. This is also known as the Ownership DSL, as it is typically used to define ownership permissions.

• For Permits: author_of(Article).can :read
• For Permissions: Article#author

User Account

Here you can set the base account class, similarly as described for User. It is used when trying to create a Guest account, in case no account factory can be found.

CanTango.config.user_account.base_class = Account

Users

User models can be registered explicitly without using the tango_user macro. This can be done to avoid autoloading some (or all) models and instead have the models remain lazy loaded.

CanTango.config.users.register :user, User
CanTango.config.users.register :admin, AdminUser

User accounts

User account models can be registered in a similar fashion to User models.

CanTango.config.user_accounts.register :account, UserAccount