Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Main API for CanTango
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib/cantango
spec
.document
.gitignore
.rspec
Gemfile
Gemfile.lock
LICENSE.txt
README.mdown
Rakefile
VERSION
cantango-api.gemspec

README.mdown

CanTango Api

The main API for CanTango

Status: Dec 9 2011

The CanTango API has now been fully spec'ed and works as it should. There are even specs that demonstrate integration with CanTango Masquerade

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
  tango_account
end

class AdminAccount
  tango_account
end

# if masquerading enabled via 'cantango-masquerade' gem
class PublisherAccount
  tango_account :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

account_ability(current_account)
current_account_ability(: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 |account|
  account.owner_of(Post) do |owner|
    owner.can :edit
    owner.cannot :publish
  end

  account.can :create, [Blog, Article]
  account.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:

user_account_can? *args
admin_account_can? *args

user_account_cannot? *args
admin_account_cannot? *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.

current_user_account
current_admin_account

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
active_account
can?
cannot?

User

active_user
active_account
can?
cannot?

Scope APIs

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

Account

scope_account scope, options, &block # alias: account_scope
real_account 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:

session_editor_account
session_admin_account
any_account *names
guest_account
active_account
active_account= account

#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
any_account *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.

Something went wrong with that request. Please try again.