challah 0.5.4 → 0.6.0

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## Challah 0.6.0
+
+* Gem dependency updates
+* Reduced application load time by eager loading ActiveRecord and ActionController modules once they are loading instead of on gem load.
+* Lots of cleanup
+* Added scoped User finders for `find_all_by_role` and `find_all_by_permission`
+* Added routes for "/sign-in" and "/sign-out" in addition to "/login" and "/logout"
+* Sign in form by default is styled using Twitter Bootstrap compatible markup. Override `views/sessions/new.html.erb` with your own view to modify the markup.
+* Added various rake tasks for unpacking the internals of the gem into an app. (run `rake -T challah:unpack` to see details)
+
 ## Challah 0.5.4
 
 * Bug fixes for Rails v3.2.3 mass assignment defaults.

data/README.md

@@ -59,6 +59,15 @@ By default a user is marked as "active" and is able to log in to your applicatio
 
 Each user is assigned to exactly one `Role` and can also be assigned to multiple `Permission` objects as needed. Because a user can be assigned to a role (and therefore its permissions) *and* permissions on an ad-hoc basis, it is important to always check a user record for restrictions based on permissions and not to use roles as a mechanism for restricting functionality in your app.
 
+There are a few helpful scopes to help find users by role and for a particular role:
+
+    User.find_all_by_role(:administrator)       # => Finds all users that are administrators
+    User.find_all_by_permission(:manage_users)  # => Finds all users that have the :manage_users permission.
+
+To unpack the `User` model into your app so you can extend it further, run:
+
+    rake challah:unpack:user        # => Copy the User model into your app
+
 ### Permission
 
 A permission is used to identify something within your application that you would like to restrict to certain users. A permission does not inherently have any functionality of its own and is just used as a reference point for pieces of functionality in your app. A permission record requires the presence of a name and key.
@@ -69,6 +78,10 @@ If there is a role named 'Administrator' in your app, all permissions will be av
 
 The default Challah installation creates two permissions by default: `admin` and `manage_users`.
 
+To unpack the `Permission` model into your app so you can extend it further, run:
+
+    rake challah:unpack:permission        # => Copy the Permission model into your app
+
 ### Role
 
 A role is used to group together various permissions and assign them to a user. Roles can also be thought of as user groups. Each role record requires a unique name.
@@ -83,6 +96,10 @@ Once you've added a few other permissions, you can easily add them to a role. In
     role.permission_keys = %w( moderator )
     role.save
 
+To unpack the `Role` model into your app so you can extend it further, run:
+
+    rake challah:unpack:role        # => Copy the Role model into your app
+
 ## Restricted access
 
 One of the main reasons to use a user- and permission-based system is to restrict access to certain portions of your application. Challah provides basic restriction methods for your controllers, views and directly from any User instance.
@@ -106,7 +123,7 @@ For example, restrict the second list item to only users that have logged in:
 Controllers can also be restricted using `before_filter`:
 
     class WidgetsController < ApplicationController
-      before_filter :login_required
+      before_filter :signin_required
 
       # …
     end
@@ -143,7 +160,7 @@ Anywhere you can access a user instance, you can use the `has` method and pass i
       <li><a href="/public-stuff">Not-so-secret Stuff</a></li>
     </ul>
 
-Notice that we checked for existance of the user before we checked to see if the user has a permission. If you used the `restrict_to_authenticated` method in your controller, you can likely skip this step.
+Notice that we checked for existence of the user before we checked to see if the user has a permission. If you used the `restrict_to_authenticated` method in your controller, you can likely skip this step.
 
 Note: `current_user` will return `nil` if there is no user available, so checking for `current_user?` prevents you from calling `has` on `nil`.
 
@@ -183,22 +200,40 @@ Whichever method you use will yield the same results. Just make sure you are che
 
 ## Default Routes
 
-By default, there are a few routes included with the Challah engine. These routes provide a basic method for a username- and password-based login page. These routes are:
+By default, there are a few routes included with the Challah engine. These routes provide a basic method for a username- and password-based sign in page. These routes are:
 
-    GET   /login        # => SessionsController#new
-    POST  /login        # => SessionsController#create
-    GET   /logout       # => SessionsController#new
+    GET   /sign-in      # => SessionsController#new
+    POST  /sign-in      # => SessionsController#create
+    GET   /sign-out     # => SessionsController#new
 
 Feel free to override the `SessionsController` with something more appropriate for your app.
 
-If you'd prefer to set up your own login/logout actions, you can skip the inclusion of the default routes by adding the following line to an initializer file in your app:
+If you'd prefer to set up your own "sign in" and "sign out" actions, you can skip the inclusion of the default routes by adding the following line to an initializer file in your app:
 
     Challah.options[:skip_routes] = true
 
+Note: These routes have changed from previous versions of Challah. `signin_path` and `signout_path` are now the preferred routes, instead of the legacy `login_path` and `logout_path`. However, the legacy routes still remain for backward compatibility.
+
+## Sign In Form
+
+By default, the sign in form is tucked away within the Challah gem. If you'd like to customize the markup or functionality of the sign in form, you can unpack it into your app by running:
+
+    rake challah:unpack:views        # => Copy the sign in view into your app
+
+If necessary, the sessions controller which handles creating new sessions and signing users out can also be unpacked into your app. This is really only recommended if you need to add some custom behavior or have advanced needs.
+
+    rake challah:unpack:signin        # => Copy the sessions controller into your app
+
 ## Full documentation
 
 Documentation is available at: [http://rubydoc.info/gems/challah](http://rubydoc.info/gems/challah/frames)
 
+## Example App
+
+A fully-functional example app, complete with some basic tests, is available at [http://challah-example.herokuapp.com/](http://challah-example.herokuapp.com/).
+
+The source code to the example is available at [https://github.com/jdtornow/challah-example](https://github.com/jdtornow/challah-example).
+
 ### Issues
 
 If you have any issues or find bugs running Challah, please [report them on Github](https://github.com/jdtornow/challah/issues). While most functions should be stable, Challah is still in its infancy and certain issues may be present.

data/app/controllers/challah/test/restrictions_controller.rb

@@ -1,25 +1,30 @@
 # @private
 # This controller is only used for testing purposes, it does not actually get used outside of test.
 class Challah::Test::RestrictionsController < ApplicationController
-  before_filter :login_required, :only => [ :edit ]
+  signin_required :only => [ :blah ]
+  before_filter :signin_required, :only => [ :edit ]
   restrict_to_permission :special, :only => [ :new ]
   restrict_to_authenticated :only => [ :show ]
-  
+
   def index
     current_user
-    
+
     head :ok
   end
-  
+
   def new
     head :ok
   end
-  
+
   def show
     head :ok
   end
-  
-  def edit    
+
+  def edit
+    head :ok
+  end
+
+  def blah
     head :ok
   end
 end

data/app/controllers/sessions_controller.rb

@@ -1,37 +1,40 @@
 class SessionsController < ApplicationController
   before_filter :destroy_session, :except => :create
-  
+
   unloadable
-  
+
   # GET /login
+  # GET /sign-in
   def new
     @session = Challah::Session.new(request)
   end
-  
+
   # POST /login
+  # POST /sign-in
   def create
     @session = Challah::Session.new(request, params[:session])
     @session.ip = request.remote_ip
-    
+
     if @session.save
       redirect_to return_to_path(@session.default_path)
     else
-      redirect_to login_path, :alert => I18n.translate('sessions.create.failed_login')
+      redirect_to signin_path, :alert => I18n.translate('sessions.create.failed_login')
     end
   end
-  
+
   # GET /logout
+  # GET /sign-out
   def destroy
-    redirect_to login_path
+    redirect_to signin_path
   end
-  
+
   protected
     def destroy_session
       current_user_session.destroy
     end
-  
+
     def return_to_path(default_path = '/')
-      result = session[:return_to]      
+      result = session[:return_to]
       result = nil if result and result == "http://#{request.domain}/"
       result || default_path
     end

data/app/models/permission.rb

@@ -1,3 +1,9 @@
 class Permission < ActiveRecord::Base
+  # Set up Challah's Permission methods. Keep this as the first line of your model to include
+  # all methods by default. You can override methods after this line as necessary.
+  #
+  # For a list of all methods included into Permission, see:
+  #
+  # http://rubydoc.info/gems/challah
   authable_permission
 end

data/app/models/role.rb

@@ -1,3 +1,9 @@
 class Role < ActiveRecord::Base
+  # Set up Challah's Role methods. Keep this as the first line of your model to include
+  # all methods by default. You can override methods after this line as necessary.
+  #
+  # For a list of all methods included into Role, see:
+  #
+  # http://rubydoc.info/gems/challah
   authable_role
 end

data/app/models/user.rb

@@ -1,3 +1,16 @@
 class User < ActiveRecord::Base
+  # Set up Challah's User methods. Keep this as the first line of your model to include
+  # all methods by default. You can override methods after this line as necessary.
+  #
+  # For a list of all methods included into User, see:
+  #
+  # http://rubydoc.info/gems/challah
   authable_user
+
+  # Uncomment the following line to add additional attributes to protect using the
+  # User#update_account_attributes(params) methods
+  #
+  # Note: This does not affect User#update_attributes
+  #
+  # protect_attributes :your_attributes, :here
 end

data/app/views/sessions/access_denied.html.erb

@@ -1,3 +1,7 @@
-<h2>Access Denied</h2>
+<div class="page-header">
+  <h1>Access Denied</h1>
+</div>
 
-<p>You do not have access to this page.</p>
+<div class="alert alert-block alert-error">
+  You do not have access to view this page.
+</div>

data/app/views/sessions/new.html.erb

@@ -1,13 +1,33 @@
-<h2>Log in</h2>
+<div class="page-header">
+  <h1>Sign In</h1>
+</div>
 
-<%= form_for(@session, :as => :session, :url => login_path, :method => :post, :html => { :id => 'log-in-form'}) do |f| %>
-  <dl>
-    <dt><%= f.label :username, t('.user_or_email') %></dt>
-    <dd><%= f.text_field :username, :size => 40, :maxlength => 200 %></dd>
+<% if flash[:alert] %>
+  <div class="alert alert-block alert-error">
+    <%= flash[:alert] %>
+  </div>
+<% end %>
 
-    <dt><%= f.label :password, t('.password') %></dt>
-    <dd class="last"><%= f.password_field :password, :size => 40, :maxlength => 200 %></dd>
-  </dl>
+<%= form_for(@session, :as => :session, :url => signin_path, :method => :post, :html => { :id => 'log-in-form'}) do |f| %>
+  <div class="row">
+    <div class="span6 form-horizontal">
+      <div class="control-group">
+        <%= f.label :username, t('.user_or_email'), :class => 'control-label' %>
 
-  <p class="submit"><%= f.submit t('.login') %></p>
+        <div class="controls">
+          <%= f.text_field :username, :size => 40, :maxlength => 200, :class => 'span3' %>
+        </div>
+      </div>
+
+      <div class="control-group">
+        <%= f.label :password, t('.password'), :class => 'control-label' %>
+
+        <div class="controls">
+          <%= f.password_field :password, :size => 40, :maxlength => 200, :class => 'span3' %>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="form-actions"><%= f.submit t('.signin'), :class => 'btn btn-primary' %></div>
 <% end %>

data/config/locales/en.yml

@@ -7,8 +7,9 @@ en:
         invalid_key: 'is not valid. Please use only lower cased letters and underscores.'
   sessions:
     new:
-      user_or_email: "Username or email address"
-      password: "Password"
+      user_or_email: "Username or email:"
+      password: "Password:"
       login: "Log in"
+      signin: "Sign in"
     create:
-      failed_login: "There was a problem logging you in. Please check your username and password and try again."
+      failed_login: "There was a problem signing you in. Please check your username and password and try again."

data/db/migrate/20120127150433_create_users.rb

@@ -1,26 +1,26 @@
 class CreateUsers < ActiveRecord::Migration
   def up
     create_table :users do |t|
-      t.string :first_name
-      t.string :last_name
-      t.string :username
-      t.string :email
-      t.string :crypted_password
-      t.string :persistence_token
-      t.string :api_key
-      t.integer :role_id
-      t.datetime :last_session_at
-      t.string :last_session_ip
-      t.integer :session_count, :default => 0
-      t.integer :failed_auth_count, :default => 0      
-      t.integer :created_by, :default => 0
-      t.integer :updated_by, :default => 0
-      t.datetime :created_at
-      t.datetime :updated_at
-      t.boolean :active, :default => true
-      t.timestamps :null => true
+      t.string      :first_name
+      t.string      :last_name
+      t.string      :username
+      t.string      :email
+      t.string      :crypted_password
+      t.string      :persistence_token
+      t.string      :api_key
+      t.integer     :role_id
+      t.datetime    :last_session_at
+      t.string      :last_session_ip
+      t.integer     :session_count, :default => 0
+      t.integer     :failed_auth_count, :default => 0
+      t.integer     :created_by, :default => 0
+      t.integer     :updated_by, :default => 0
+      t.datetime    :created_at
+      t.datetime    :updated_at
+      t.boolean     :active, :default => true
+      t.timestamps  :null => true
     end
-    
+
     add_index :users, :username
     add_index :users, :first_name
     add_index :users, :last_name

data/db/migrate/20120127150434_create_roles.rb

@@ -1,10 +1,10 @@
 class CreateRoles < ActiveRecord::Migration
   def up
     create_table :roles do |t|
-      t.string :name
-      t.text :description
-      t.string :default_path, :default => '/'
-      t.boolean :locked, :default => false
+      t.string      :name
+      t.text        :description
+      t.string      :default_path, :default => '/'
+      t.boolean     :locked, :default => false
       t.timestamps
     end
   end

data/db/migrate/20120127150435_create_permissions.rb

@@ -1,12 +1,12 @@
 class CreatePermissions < ActiveRecord::Migration
   def up
     create_table :permissions do |t|
-      t.string :name
-      t.text :description
-      t.string :key, :limit => 50
-      t.boolean :locked, :default => false
+      t.string      :name
+      t.text        :description
+      t.string      :key, :limit => 50
+      t.boolean     :locked, :default => false
     end
-    
+
     add_index :permissions, :key
   end
 

data/db/migrate/20120127150436_create_permission_roles.rb

@@ -1,10 +1,10 @@
 class CreatePermissionRoles < ActiveRecord::Migration
   def up
     create_table :permission_roles do |t|
-      t.integer :role_id
-      t.integer :permission_id
+      t.integer     :role_id
+      t.integer     :permission_id
     end
-    
+
     add_index :permission_roles, :role_id
     add_index :permission_roles, :permission_id
   end

data/db/migrate/20120127150437_create_permission_users.rb

@@ -1,10 +1,10 @@
 class CreatePermissionUsers < ActiveRecord::Migration
   def up
     create_table :permission_users do |t|
-      t.integer :user_id
-      t.integer :permission_id
+      t.integer     :user_id
+      t.integer     :permission_id
     end
-    
+
     add_index :permission_users, :user_id
     add_index :permission_users, :permission_id
   end

data/db/seeds.rb

@@ -1,12 +1,46 @@
 # Add default admin permission and role and normal user with no permissions
 if Permission.count.zero? and Role.count.zero?
-  admin_permission = Permission.create!({ :name => 'Administrator', :key => 'admin', :description => 'Administrative users have unrestricted access to all components within the application.', :locked => true }, :without_protection => true)
-  manage_users_permission = Permission.create!({ :name => 'Manage Users', :key => 'manage_users', :description => 'Access to add, edit and remove application users.', :locked => true }, :without_protection => true)
+  # Create the admin permission.
+  admin_permission = Permission.create!({
+    :name => 'Administrator',
+    :key => 'admin',
+    :description => 'Administrative users have unrestricted access to all components within the application.',
+    :locked => true
+    }, :without_protection => true)
 
-  admin_role = Role.create!({ :name => 'Administrator', :description => 'Administrative users have unrestricted access to all components within the application.', :default_path => '/', :locked => true }, :without_protection => true)
+  # Create the manage users permission
+  manage_users_permission = Permission.create!({
+    :name => 'Manage Users',
+    :key => 'manage_users',
+    :description => 'Access to add, edit and remove application users.',
+    :locked => true
+    }, :without_protection => true)
 
-  PermissionRole.create!({ :role_id => admin_role.id, :permission_id => admin_permission.id }, :without_protection => true)
-  PermissionRole.create!({ :role_id => admin_role.id, :permission_id => manage_users_permission.id }, :without_protection => true)
+  # Create the admin role
+  admin_role = Role.create!({
+    :name => 'Administrator',
+    :description => 'Administrative users have unrestricted access to all components within the application.',
+    :default_path => '/',
+    :locked => true
+    }, :without_protection => true)
 
-  normal_role = Role.create!({ :name => 'Default', :description => 'Default users can log in to the application.', :default_path => '/' }, :without_protection => true)
+  # Make sure admin role has the admin permission
+  PermissionRole.create!({
+    :role_id => admin_role.id,
+    :permission_id => admin_permission.id
+    }, :without_protection => true)
+
+
+  # Make sure the admin role has the manage_users permission
+  PermissionRole.create!({
+    :role_id => admin_role.id,
+    :permission_id => manage_users_permission.id
+    }, :without_protection => true)
+
+  # Set up the default user role, this role has no permissions.
+  Role.create!({
+    :name => 'Default',
+    :description => 'Default users can log in to the application.',
+    :default_path => '/'
+    }, :without_protection => true)
 end

data/lib/challah/authable/role.rb

@@ -61,18 +61,35 @@ module Challah
       end
 
       class_eval do
-        validates_presence_of :name
-        validates_uniqueness_of :name
+        # Validations
+        ################################################################
 
-        has_many :users, :order => 'users.first_name, users.last_name'
-        has_many :permission_roles, :dependent => :destroy
-        has_many :permissions, :through => :permission_roles, :order => 'permissions.name'
+        validates :name, :presence => true, :uniqueness => true
+
+        # Relationships
+        ################################################################
+
+        has_many :permission_roles,   :dependent => :destroy
+
+        has_many :permissions,        :through => :permission_roles,
+                                      :order => 'permissions.name'
+
+        has_many :users,              :order => 'users.first_name, users.last_name'
+
+        # Scoped Finders
+        ################################################################
 
         default_scope order('roles.name')
 
-        attr_accessible :name, :description, :default_path, :locked
+        # Callbacks
+        ################################################################
 
         after_save :save_permission_keys
+
+        # Attributes
+        ################################################################
+
+        attr_accessible :description, :default_path, :locked, :name
       end
     end