burlesque 2.0.1 → 2.0.3

data/README.md

@@ -1,48 +1,213 @@
-Burlesque
-=========
+# Burlesque
 
-Crea estructura de roles y grupos para cualquier modelo, considera además las 3 tablas de _join_ que pudiesen darse.
+Create roles and groups structures for any model, also creates the 3 _join_ tables.
 
-Installation
-------------
+## Installation
 
-Before you can use the generator, add the gem to your project's Gemfile as follows:
+In order to use the generator, add the gem to your project's `Gemfile` as follows:
 
-```
+```ruby
 gem 'burlesque'
 ```
 
 Then install it by running:
 
-```
+```bash
 bundle install
 ```
 
-After, bootstrap your Rails app, for example:
+Then bootstrap your Rails app:
 
-```
+```bash
 rake burlesque:install:migrations
 rake db:migrate
 ```
 
-If you would like to run migrations only from Burlesque engine, you can do it by specifying SCOPE:
+Note that if you want to run **only** the Burlesque migrations, you can use the `SCOPE` option:
 
-```
+```bash
 rake db:migrate SCOPE=burlesque
 ```
 
-Finally, in model that you need burlesque:
+Finally, enable Burlesque in each model:
+
+```ruby
+class User < ActiveRecord::Base
+  include Burlesque::Admin
+
+  # ...
+end
+```
+
+## Defining Role's
+
+You can define/create all RESTful roles at once with:
+
+```
+Burlesque::Role.for 'user' # String, or
+Burlesque::Role.for :user  # Symbol, or
+Burlesque::Role.for User   # Constant
+```
+
+This will create the following authorizations:
+
+Action  | Resource | Description
+:-------|:---------|:-----------
+Read    | User     | Can see list of all Users or single User details
+Create  | User     | Can create a new User (:new, :create)
+Update  | User     | Can Update a User (:edit, :update)
+Destroy | User     | Can delete a User
+
+
+## Defining Group's
+
+Group names must be unique. The best way to define Burlesque groups is:
+
+```
+Burlesque::Group.find_or_create_by_name('Admin')
+```
+
+## Group's and Role's
 
+To assign a list of `Burlesque::Role` identifiers to a `Burlesque::Group` just do:
+
+```ruby
+group = Burlesque::Group.find_by_name('Admin')
+group.push_roles [role, another_role]  # role and antoher_role are instances of Burlesque::Role
 ```
-include Burlesque::Admin
+
+The `push_roles` method ensures the roles are only added once to the group. If you want to assign the groups by yourself, please take care with that. Otherwise, Burlesque will raise an `ActiveRecord::RecordInvalid` exception.
+
+
+## Utility functions
+
+Assuming you enabled **Burlesque** in your model `User`:
+
+### Questions
+
+Ask for groups:
+
+```ruby
+user.group?(group)   # group is an instance of Burlesque::Group
+user.group?('Admin') # it also works with groups names
+```
+
+Ask for roles:
+
+```ruby
+user.role?(role)         # role is an instance of Burlesque::Role
+user.role?('all#manage') # again, it also works with names
 ```
 
+Since an user may have `Burlesque::Role` without necessarily belonging to a `Burlesque::Group`, you may want to know if a given _role_ is provided by the belonging to a `Burlesque::Group`, or not.
 
+```ruby
+user.role_in_groups?(role)         # role is an instance of Burlesque::Role
+user.role_in_groups?('all#manage')
+```
 
-CanCan
-------
+### MassAssignment
 
-Burlesque makes no assumption about how auhtorizations are handled in your application. However it integrates nicely with [CanCan][cancan]; all you have to do is define the `Ability` model as follows:
+To assign a list of groups to an user:
+
+```ruby
+ids = [1, 3, 4]  # groups identifiers
+user.group_ids = (ids)
+```
+
+To assign a list of roles to an user:
+
+```ruby
+ids = [6, 7, 9]  # roles identifiers
+user.role_ids = (ids)
+```
+
+
+### Search
+
+You can search `Burlesque::Role` using defined SCOPE search and combine them any way you need.
+
+Scope         | Description
+:-------------|:-----------
+action        | To search for `Burlesque::Role` that are associated with the same action.
+not_action    | To search for `Burlesque::Role` that are not associated with the same action.
+resource      | To search for `Burlesque::Role` that are linked to a resource in question
+not_resource  | To search for `Burlesque::Role` that are not linked to a resource in question
+
+Example:
+
+```ruby
+Burlesque::Role.action('read')   # String, or
+Burlesque::Role.action(:read)    # Symbol
+
+Burlesque::Role.resource('user') # String, or
+Burlesque::Role.resource(:user)  # Symbol, or
+Burlesque::Role.resource(User)   # Constant
+```
+
+# I18n
+
+If you want to translate the roles names, you can use the `translate_name` method:
+
+```ruby
+role = Burlesque::Role.action(:read).resource(:user)
+name = role.translate_name()  #  where role is an instance of Burlesque::Role to be translated
+# => 'Read User'
+```
+
+The translation is handled by a YML file. If you only have RESTful actions, it may not be necessary to translate the roles by hand, as Burlesque will automagically use the model translations to compose human-friendly strings:
+
+
+```ruby
+Burlesque::Role.create(name: 'user#read'   ).translate_name()  ==>  Read User
+Burlesque::Role.create(name: 'user#create' ).translate_name()  ==>  Create User
+Burlesque::Role.create(name: 'user#update' ).translate_name()  ==>  Read User
+Burlesque::Role.create(name: 'user#destroy').translate_name()  ==>  Destroy User
+Burlesque::Role.create(name: 'user#manage' ).translate_name()  ==>  Manage User
+```
+
+However, you are free to override the Burlesque defaults (e.g. for localization, here in Spanish):
+
+```yaml
+es:
+  authorizations:
+    read: Leer
+    create: Crear
+    update: Actualizar
+    destroy: Eliminar
+    manage: Administrar
+```
+
+```ruby
+# Provided Spanish is the default language of your app
+Burlesque::Role.create(name: 'user#read'   ).translate_name()  ==>  Leer Usuarios
+Burlesque::Role.create(name: 'user#create' ).translate_name()  ==>  Crear Usuarios
+Burlesque::Role.create(name: 'user#update' ).translate_name()  ==>  Actualizar Usuarios
+Burlesque::Role.create(name: 'user#destroy').translate_name()  ==>  Eliminar Usuarios
+Burlesque::Role.create(name: 'user#manage' ).translate_name()  ==>  Administrar Usuarios
+```
+
+If what you want is to change the translation of a single `Burlesque::Role`, you can:
+Finally, in case you were not satisfied by the generated translations, you can define your own:
+
+```yaml
+es:
+  authorizations:
+    user#read: 'Read Awesome Users'
+```
+
+```ruby
+Burlesque::Role.action(:read).resource(:user).translate_name()  ==>  Read Awesome Users
+Burlesque::Role.find_by_name('user#read').translate_name()      ==>  Read Awesome Users
+```
+
+# Contributing
+
+TODO
+
+# CanCan
+
+Burlesque makes no assumption about how auhtorizations are handled in your application. However it integrates nicely with [CanCan][cancan] all you have to do is define the `Ability` model as follows:
 
 ```ruby
 class Ability
@@ -62,7 +227,7 @@ end
 
   [cancan]: https://github.com/ryanb/cancan
 
-Todo
-----
+
+# Todo
 
 Rake task for burlesque admin module inclusion.

data/app/models/burlesque/role.rb

@@ -18,10 +18,10 @@ module Burlesque
 
     SPLITER = '#'
 
-    scope :action,        lambda { |action| where('name LIKE ?',     "%#{SPLITER}#{action}")     }
-    scope :not_action,    lambda { |action| where('name NOT LIKE ?', "%#{SPLITER}#{action}")     }
-    scope :resource,      lambda { |model|  where('name LIKE ?',     "#{model.to_s}#{SPLITER}%") }
-    scope :not_resource,  lambda { |model|  where('name NOT LIKE ?', "#{model.to_s}#{SPLITER}%") }
+    scope :action,        lambda { |action| where('name LIKE ?',     "%#{SPLITER}#{action}")                }
+    scope :not_action,    lambda { |action| where('name NOT LIKE ?', "%#{SPLITER}#{action}")                }
+    scope :resource,      lambda { |model|  where('name LIKE ?',     "#{model.to_s.underscore}#{SPLITER}%") }
+    scope :not_resource,  lambda { |model|  where('name NOT LIKE ?', "#{model.to_s.underscore}#{SPLITER}%") }
 
     # Public: Relacion a muchos usuarios
     #
@@ -44,7 +44,11 @@ module Burlesque
       translate = I18n.t(name.to_sym, scope: :authorizations)
       return translate unless translate.include?('translation missing:')
 
-      translate = I18n.t(action_sym, scope: :authorizations) + ' ' + resource_class.model_name.human
+      begin
+        translate = I18n.t(action_sym, scope: :authorizations) + ' ' + resource_class.model_name.human
+      rescue
+        translate = I18n.t(action_sym, scope: :authorizations) + ' ' + resource_class.to_s
+      end
     end
 
     # Public: Entrega el recurso asociado al rol.

data/config/locales/burlesque.es-CL.yml

@@ -16,6 +16,7 @@
     attributes:
       role:
         name: Nombre
+        groups: Grupos
         created_at: Creado
         updated_at: Última actualización
       group:

data/lib/burlesque/version.rb

@@ -1,3 +1,3 @@
 module Burlesque
-  VERSION = "2.0.1"
+  VERSION = "2.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: burlesque
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-26 00:00:00.000000000 Z
+date: 2013-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails