CanTango Api

The main API for CanTango

Status: Dec 9 2011

The CanTango API has now been almost fully spec'ed. All specs except for CanTango::Ability::Dsl now pass :)

Dependencies

This extension depends on the CanTango core and follows the extension conventions as described there.

Core extensions

Macro modules

  • CanTango::Api::Macros::
    • Account
    • User
    • Clazz

These macro modules allow registration of CanTango User and Account models.

Note: These should perhaps be wrapped in a Model namespace? See '-core'

Account model registration

class UserAccount
  
end

class AdminAccount
  
end

# if masquerading enabled via 'cantango-masquerade' gem
class PublisherAccount
   :masquerade
end

User model registration

class User
  tango_user 
end

class Admin
  tango_user
end

# if masquerading enabled via 'cantango-masquerade' gem
class Publisher
  tango_user :masquerade
end

Generic model registration

The Clazz macro module uses naming conventions to determine if the model is a User or Account model.

class UserAccount
  cantango
end

class Admin
  cantango
end

# if masquerading enabled via 'cantango-masquerade' gem
class PublisherAccount
  cantango :masquerade
end

Main APIs

The main API consists of the following:

  • CanTango::Api::
    • Ability
    • Can
    • Model
    • Scope
    • Session

Each of these have a specific variant for both Account and User.

Ability

  • CanTango::Api::Ability
    • Account
    • User
    • Dsl
    • Relationship
    • Relation
    • Scope

Account

()
(:admin)

User

user_ability(current_user)
current_user_ability(:editor)

Dsl

The Dsl API extends the Ability API with Relation and Scope APIs. When The Ability::Dsl module is included, both these APIs are included into the target.

Dsl - Relation

owner_of(Post).can :edit
owner_of(Post).cannot :publish

owner_of(Post). do |owner|
  owner.can :edit
  owner.cannot :publish
end

This DSL creates a Relation object with #can and #cannot methods that delegate the wrapped ability.

Dsl - Scope

Do relationship on Ability #user (also the default scope)

scope :user do |user|
  user.owner_of(Post).can :edit
  user.owner_of(Post).cannot :publish

  user.owner_of(Post). do |owner|
    owner.can :edit
    owner.cannot :publish
  end
end

This DSL creates a Scope object that wraps an ability. It also includes the Relation API.

Do relationship on Ability #account

scope :account do ||
  .owner_of(Post) do |owner|
    owner.can :edit
    owner.cannot :publish
  end

  .can :create, [Blog, Article]
  .cannot [:create, :delete], User
  # ...
end

Can API

  • CanTango::Api::Can
    • Account
    • User

Account

Assuming we have registered the following types of accounts:

CanTango.config.accounts.registered # => [:user, admin]

Then the following methods become available when this module is included:

 *args
 *args

 *args
 *args

The following methods are generated by this module, but by default simply forward to #current_user and #current_admin respectively. It is up to the developer to implement these methods to suit the application scenario.



User

Assuming we have registered the following types of accounts:

CanTango.config.users.registered # => [:user, admin]

Then the following methods become available when this module is included:

user_can? *args
admin_can? *args

user_cannot? *args
admin_cannot? *args

It is up to the developer to make the following methods available. If Devise is used, methods of the form #current_[user class] are generated for each Devise user model.

current_user
current_admin

Model APIs

  • CanTango::Api::Model
    • Account
    • User

Note: The Macros for User and Account (tango_user, tango_account, ...) might be moved under this namespace later.

Account

active_user

can?
cannot?

User

active_user

can?
cannot?

Scope APIs

  • CanTango::Api::Scope
    • Account
    • User

Account

 scope, options, &block # alias: account_scope
 scope, options, &block

#scope_account can be used to make multiple AC checks within a block on a specific account. This method will use the masqueraded account if an account being masqueraded.

#real_account is similar to #scope_account, but ignores any masquerading, applying the AC checks on the "real" account, not the one being masqueraded (faked).

User

scope_user scope, options, &block # alias: user_scope
real_user scope, options, &block

#scope_user can be used to make multiple AC checks within a block on a specific user. This method will use the masqueraded user if a user being masqueraded.

#real_user is similar to #scope_user, but ignores any masquerading, applying the AC checks on the "real" user, not the one being masqueraded (faked).

Session APIs

  • CanTango::Api::Session
    • Account
    • User

Account

Assuming we have registered the following types of accounts:

CanTango.config.accounts.registered # => [:editor, admin]

Then the following methods become available when this module is included:



 *names


= 

#any_account will return the first account for which a name matches. If no account matches are found it will default to return the guest account. To find users, it will use the #current_[account type] methods.

User

Assuming we have registered the following types of users:

CanTango.config.users.registered # => [:user, admin]

Then the following methods become available when this module is included:

session_user
session_admin
 *names
guest_user
active_user
active_user= user

#any_user will return the first user for which a name matches. If no user matches are found it will default to return the guest user. To find users, it will use the #current_[user type] methods.

Contributing to cantango-api

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2011 Kristian Mandrup. See LICENSE.txt for further details.