thoughtbot-clearance 0.3.7 → 0.3.8

data/README.textile

@@ -1,33 +1,38 @@
 h1. Clearance
 
-Simple, complete Ruby web app authentication. 
+Rails authentication for developers who write tests.
 
 "We have clearance, Clarence.":http://www.youtube.com/v/mNRXJEE3Nz8
 
+h2. Integration with Suspenders
+
+Clearance is based on the same conventions and tools as "Suspenders":http://github.com/thoughtbot/suspenders Thus if you use it, you may already have some configuration mentioned below in place.
+
 h2. Gem installation (Rails 2.1+)
 
-In config/environments/test.rb:
+In config/environment.rb:
 
     config.gem 'mocha'
     config.gem 'thoughtbot-shoulda',
-      :lib    => 'shoulda',
-      :source => "http://gems.github.com"
+      :lib     => 'shoulda',
+      :source  => "http://gems.github.com", 
+      :version => '>= 2.0.6'
     config.gem 'thoughtbot-factory_girl',
-      :lib    => 'factory_girl',
-      :source => "http://gems.github.com"
-
-In config/environment.rb:
-
-    config.gem "thoughtbot-clearance", :lib => 'clearance', :source => 'http://gems.github.com'
+      :lib     => 'factory_girl',
+      :source  => "http://gems.github.com", 
+      :version => '>= 1.1.5'
+    config.gem "thoughtbot-clearance", 
+      :lib     => 'clearance', 
+      :source  => 'http://gems.github.com'
 
 Then:
 
     rake gems:install
     rake gems:unpack
 
-h2. Generator
+h2. The generator
 
-In a greenfield application, just run the generator:
+In a greenfield application, make sure the development database exists and just run the generator:
 
     script/generate clearance
 
@@ -39,7 +44,6 @@ This will create:
     app/controllers/users_controller.rb
     app/models/user.rb
     app/models/user_mailer.rb
-    app/views/confirmations/new.html.erb
     app/views/passwords/edit.html.erb
     app/views/passwords/new.html.erb
     app/views/sessions/new.html.erb
@@ -52,29 +56,64 @@ This will create:
     test/functional/passwords_controller_test.rb
     test/functional/sessions_controller_test.rb
     test/functional/users_controller_test.rb
-    test/unit/user_mailer_test.rb
+    test/unit/clearance_mailer_test.rb
     test/unit/user_test.rb
 
-Add the corresponding Clearance module for any file(s) you don't want to override. They are namespaced exactly like the directory structure of a Rails app: 
+You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.
 
-    app/models/user.rb already exists.
-    include Clearance::App::Models::User
+h2. Modules
 
-h2. Tests
+Clearance works by mixing behavior into tests, controllers, and models. For any file that you do not want to overwrite, include the corresponding Clearance module. They are namespaced exactly like the directory structure of a Rails app.
 
-The tests use "Shoulda":http://thoughtbot.com/projects/shoulda >= 2.0.4 and "Factory Girl":http://thoughtbot.com/projects/factory_girl. You should create a User Factory:
+Application controller example:
 
-    Factory.sequence :email do |n|
-      "user#{n}@example.com"
+    class ApplicationController < ActionController::Base
+      include Clearance::App::Controllers::ApplicationController
     end
 
-    Factory.define :user do |user|
-      user.email { Factory.next :email }
-      user.password "password"
-      user.password_confirmation "password"
+User model example:
+
+    class User < ActiveRecord::Base
+      include Clearance::App::Models::User
     end
 
-In test/test_helper.rb: 
+User test example:
+
+    class UserTest < Test::Unit::TestCase
+      include Clearance::Test::Unit::UserTest
+    end
+
+h2. The migration    
+    
+The generator will also create a migration to add a "users" table and run it. If the table already exists in the database, the migration will just add fields and indexes that are missing and required by Clearance. If the migration fails, the generator will revert all changes back.
+
+h2. Routes
+
+Clearance will add these routes to your routes.rb:
+
+    map.resources :users, :has_one => [:password, :confirmation]
+    map.resource :session
+    map.resources :passwords
+    
+Please note that Clearance depends on root_url, so please make sure that it is defined to *something* in your config/routes.rb:
+
+    map.root :controller => 'home'
+    
+h2. Environments
+
+You need to define HOST constant in your environments files. In config/environments/test.rb and config/environments/development.rb it can be:
+
+    HOST = "localhost"
+
+While in config/environments/production.rb it must be the actual host your application is deployed to because the constant is used by mailers to generate URLs in emails.
+
+In config/environment.rb:
+
+    DO_NOT_REPLY = "donotreply@example.com"
+
+h2. Tests
+
+The tests use "Shoulda":http://thoughtbot.com/projects/shoulda >= 2.0.4 and "Factory Girl":http://thoughtbot.com/projects/factory_girl. You need to add the Clearance module to your test/test_helper.rb:
 
     class Test::Unit::TestCase
       self.use_transactional_fixtures = true
@@ -82,53 +121,100 @@ In test/test_helper.rb:
       include Clearance::Test::TestHelper
     end
 
-h2. Controllers
+The generator will create a user factory in test/factories/clearance_user.rb unless
+you have it defined somewhere else.
 
-In app/controllers/application_controller.rb:
+h2. Usage: basic workflow
 
-    class ApplicationController < ActionController::Base
-      helper :all
-      protect_from_forgery
-      include Clearance::App::Controllers::ApplicationController
-    end
+Rails authentication with Clearance uses the standard approach thoughtbot and our clients have agreed upon. 
 
-h2. Migration
+Users register (UsersController) using an email address and a password (User model). They get an email with a confirmation link (ClearanceMailer) to confirm their registration (ConfirmationController).
 
-Your users table needs a few columns.
+Registered users can sign in and out (SessionsController). If they forget their password, they request an email containing a link to change it (PasswordsController). 
 
-    create_table(:users) do |t|
-      t.string :email
-      t.string :crypted_password, :limit => 40
-      t.string :salt, :limit => 40
-      t.string :remember_token
-      t.datetime :remember_token_expires_at
-      t.boolean :confirmed, :default => false, :null => false
-    end
+h2. Usage: actions which require an authenticated user
 
-    add_index :users, [:email, :crypted_password]
-    add_index :users, [:id, :salt]
-    add_index :users, :email
-    add_index :users, :remember_token
+To protect your controllers with authentication add:
 
-h2. Routes
+    class ProtectedController < ApplicationController
+      before_filter :authenticate
 
-    map.resources :users
-    map.resource :session
-    map.resources :users, :has_one => :password
-    map.resources :users, :has_one => :confirmation
-    map.resources :passwords
-    map.root :controller => 'sessions', :action => 'new'
+The filter will ensure that only authenticated users can access the controller. If someone who's not logged in tries to access a protected action: 
 
-h2. Environments
+* the URL is stored in the session, 
+* the user is redirected to log in page, and
+* after successful authentication will be be redirected back to that URL.
 
-In config/environments/test.rb and config/environments/development.rb:
+h2. Usage: logged_in?, current_user
 
-    HOST = "localhost"
+Clearance provides two methods that can be used in controllers, helpers, and views to check if current user is authenticated and get the actual user: 
 
-In config/environment.rb:
+* logged_in?
+* current_user
 
-    DO_NOT_REPLY = "donotreply@example.com"
-    PROJECT_NAME = "my_app_name"
+This may be familiar to you if you've used "restful_authentication":http://github.com/technoweenie/restful-authentication.
+    
+    <% if logged_in? -%>
+      Hello, <%= current_user.name %>!
+    <% else -%>
+      Please <%= link_to 'Log in', new_session_path %>
+    <% end -%>
+    
+h2. Usage: mass assignment
+
+Please note that all User attributes except email, password and password_confirmation are protected from mass assignment by default. Use attr_accessible to enable it for your custom attributes.
+    
+    class User < ActiveRecord::Base
+      include Clearance::App::Models::User
+      attr_accessible :first_name, :last_name
+    ...
+
+h2. Hooks and overwritables: return_to parameter
+
+If you want to specify where to redirect a user (say you want to have a login box on every page and redirect the user to the same page) after he/she signs in, you can add a "return_to" parameter to the request (thanks to "Phillippe":http://www.sivarg.com/2009/01/clearance-coming-from-where-your-were.html for the tip):
+
+    <% form_for :session, :url => session_path(:return_to => request.request_uri) do |form| %> 
+    ...
+
+h2. Hooks and overwritables: url_after_create, url_after_destroy
+    
+Actions that redirect (create and destroy) in Clearance controllers are customizable. If you want to redirect a user to a specific route after signing in, overwrite the "url_after_create" method in the SessionsController:
+
+    class SessionsController < ApplicationController
+      include Clearance::App::Controllers::SessionsController
+      
+      private
+      
+        def url_after_create
+          new_blog_post_path
+        end
+    end
+
+There are similar methods in other controllers as well:
+
+    UsersController#url_after_create (sign up)
+    SessionsController#url_after_create (sign in)
+    SessionsController#url_after_destroy (sign out)
+    PasswordsController#url_after_create (password reset request)
+    ConfirmationsController#url_after_create (confirmation)
+
+h2. Hooks and overrides: log_user_in
+
+Say you want to add a last_logged_in_at attribute to your User model. You would want to update it when the User logs in.
+
+Clearance has a method named log_user_in that you can override with that logic. Be sure to call login(user) at the end (and write tests!).
+
+    class ApplicationController < ActionController::Base
+      include Clearance::App::Controllers::ApplicationController
+      
+      private
+        
+        def log_user_in(user)
+          # store current time to display "last logged in at" message
+          user.update_attribute(:last_logged_in_at, Time.now)
+          login(user)
+        end
+    end 
 
 h2. Authors
 
@@ -138,3 +224,4 @@ h2. Authors
 * Mike Burns
 * Josh Nichols
 * Mike Breen
+* Eugene Bolshakov

data/Rakefile

@@ -3,22 +3,30 @@ require 'rake/testtask'
  
 test_files_pattern = 'test/rails_root/test/{unit,functional,other}/**/*_test.rb'
 namespace :test do
-  Rake::TestTask.new(:all => 'generator:tests') do |t|
-    t.libs << 'lib'
-    t.pattern = test_files_pattern
-    t.verbose = false
+  Rake::TestTask.new(:all => ['generator:cleanup', 'generator:generate']) do |task|
+    task.libs << 'lib'
+    task.pattern = test_files_pattern
+    task.verbose = false
   end
 end
 
 namespace :generator do
-  desc "Run the generator on the tests"
-  task :tests do
-    FileList["generators/clearance/templates/**/*.*"].each do |f|
-      File.delete("test/rails_root/#{f.gsub("generators/clearance/templates/",'')}")
+  desc "Cleans up the test app before running the generator"
+  task :cleanup do
+    FileList["generators/clearance/templates/**/*.*"].each do |each|
+      file = "test/rails_root/#{each.gsub("generators/clearance/templates/",'')}"
+      File.delete(file) if File.exists?(file)
     end
-    FileUtils.rm_r("test/rails_root/vendor/plugins/clearance")
+    
+    FileUtils.rm_rf("test/rails_root/db/migrate")
+    FileUtils.rm_rf("test/rails_root/vendor/plugins/clearance")
+    system "cp generators/clearance/templates/config/routes.rb test/rails_root/config"      
     system "mkdir -p test/rails_root/vendor/plugins/clearance"
-    system "cp -R generators test/rails_root/vendor/plugins/clearance"
+    system "cp -R generators test/rails_root/vendor/plugins/clearance"  
+  end
+
+  desc "Run the generator on the tests"
+  task :generate do
     system "cd test/rails_root && ./script/generate clearance"
   end
 end
@@ -26,20 +34,20 @@ end
 desc "Run the test suite"
 task :default => 'test:all'
 
-spec = Gem::Specification.new do |s|
-  s.name = "clearance"
-  s.version = '0.3.7'
-  s.summary = "Simple, complete Rails authentication."
-  s.email = "support@thoughtbot.com"
-  s.homepage = "http://github.com/thoughtbot/clearance"
-  s.description = "Simple, complete Rails authentication scheme."
-  s.authors = ["thoughtbot, inc.", "Josh Nichols", "Mike Breen"]
-  s.files = FileList["[A-Z]*", "{generators,lib}/**/*"]
+gem_spec = Gem::Specification.new do |gem_spec|
+  gem_spec.name = "clearance"
+  gem_spec.version = '0.3.8'
+  gem_spec.summary = "Simple, complete Rails authentication."
+  gem_spec.email = "support@thoughtbot.com"
+  gem_spec.homepage = "http://github.com/thoughtbot/clearance"
+  gem_spec.description = "Simple, complete Rails authentication scheme."
+  gem_spec.authors = ["thoughtbot, inc.", "Josh Nichols", "Mike Breen"]
+  gem_spec.files = FileList["[A-Z]*", "{generators,lib,shoulda_macros,rails}/**/*"]
 end
 
 desc "Generate a gemspec file"
 task :gemspec do
-  File.open("#{spec.name}.gemspec", 'w') do |f|
-    f.write spec.to_ruby
+  File.open("#{gem_spec.name}.gemspec", 'w') do |f|
+    f.write gem_spec.to_yaml
   end
 end

data/TODO.textile

@@ -1,20 +1,6 @@
 (highest priority first)
 
-# activation code (like restful-auth) instead of salt?
-# remove dependency on root_url?
-# generator should print out instructions to include modules existing files
-# check to make sure attr_accessible doesn't override and w/ attr_protected
-# move shoulda macros in test_helper to shoulda_macros folder
-# refactor Mailer default_url_options[:host] to something cleaner
-# application controller uses protected, all other controllers use private
-# add information about url_after_create to README or github wikis
-
-ideas to steal from merb-auth:
-
-# store current_user on the session, not controller
-# respond with 401 Unauthorized when request requires authentication 
-# respond with 405 Method Not Allowed when action requested isn’t allowed
-# 401 and 405 need to be in Exceptions controller or use safety_valve
+# existing_user? methods ... if salt is wrong, user may not be found b/c of invalid credentials. is :not_found the correct code to return in that use case? if not, method probably needs to be split into another conditional.
 # email confirmation is a strategy
 # forgot password is a strategy
 # salted password is a strategy

data/generators/clearance/clearance_generator.rb

@@ -1,10 +1,20 @@
+require File.expand_path(File.dirname(__FILE__) + "/lib/insert_commands.rb")
+require File.expand_path(File.dirname(__FILE__) + "/lib/rake_commands.rb")
+require 'factory_girl'
+
 class ClearanceGenerator < Rails::Generator::Base
   
   def manifest
     record do |m|
       m.directory File.join("app", "controllers")
-      ["app/controllers/application.rb",
-       "app/controllers/confirmations_controller.rb",
+      file = "app/controllers/application.rb"
+      if File.exists?(file)
+        m.insert_into file, "include Clearance::App::Controllers::ApplicationController"
+      else
+        m.file file, file 
+      end
+     
+      ["app/controllers/confirmations_controller.rb",
        "app/controllers/passwords_controller.rb", 
        "app/controllers/sessions_controller.rb", 
        "app/controllers/users_controller.rb"].each do |file|
@@ -12,16 +22,11 @@ class ClearanceGenerator < Rails::Generator::Base
       end
       
       m.directory File.join("app", "models")
-      ["app/models/user.rb",
-       "app/models/clearance_mailer.rb"].each do |file|
+      ["app/models/user.rb", "app/models/clearance_mailer.rb"].each do |file|
         m.file file, file
       end
       
       m.directory File.join("app", "views")
-      m.directory File.join("app", "views", "confirmations")
-      ["app/views/confirmations/new.html.erb"].each do |file|
-        m.file file, file
-      end
       
       m.directory File.join("app", "views", "passwords")
       ["app/views/passwords/new.html.erb",
@@ -61,9 +66,26 @@ class ClearanceGenerator < Rails::Generator::Base
         m.file file, file
       end
       
-      ["test/factories.rb"].each do |file|
+      m.directory File.join("test", "factories")
+      ["test/factories/clearance_user.rb"].each do |file|
         m.file file, file
       end
+      
+      m.route_resources ':passwords'      
+      m.route_resource  ':session'      
+      m.route_resources ':users, :has_one => [:password, :confirmation]'      
+      
+      if ActiveRecord::Base.connection.table_exists?(:users)      
+        m.migration_template 'db/migrate/update_users_with_clearance_columns.rb', 
+          'db/migrate', :migration_file_name => 'create_or_update_users_with_clearance_columns'
+      else
+        m.migration_template 'db/migrate/create_users_with_clearance_columns.rb', 
+          'db/migrate', :migration_file_name => 'create_or_update_users_with_clearance_columns'
+      end
+            
+      m.rake_db_migrate
+      
+      m.readme "README"
     end
   end
   

data/generators/clearance/lib/insert_commands.rb

@@ -0,0 +1,103 @@
+# Mostly pinched from http://github.com/ryanb/nifty-generators/tree/master
+
+Rails::Generator::Commands::Base.class_eval do
+  def file_contains?(relative_destination, line)
+    File.read(destination_path(relative_destination)).include?(line)
+  end
+end
+
+Rails::Generator::Commands::Create.class_eval do
+
+  def route_resources(resource_list)
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.resources #{resource_list}"
+    unless options[:pretend] || file_contains?('config/routes.rb', resource_list)
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.resources #{resource_list}"
+      end
+    end
+  end
+
+  def route_resource(resource_list)
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.resource #{resource_list}"
+    unless options[:pretend] || file_contains?('config/routes.rb', resource_list)
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.resource #{resource_list}"
+      end
+    end
+  end
+  
+  def route_name(name, path, route_options = {})
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    unless options[:pretend] 
+      gsub_file_once 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+      end
+    end
+  end
+  
+  def insert_into(file, line)
+    logger.insert "#{line} into #{file}"
+    unless options[:pretend] || file_contains?(file, line)
+      gsub_file file, /^(class|module) .+$/ do |match|
+        "#{match}\n  #{line}"
+      end
+    end
+  end
+end
+
+Rails::Generator::Commands::Destroy.class_eval do
+  def route_resource(resource_list)
+    look_for = "  map.resource #{resource_list}\n".gsub(/[\[\]]/, '\\\\\0')
+    logger.route "map.resource #{resource_list} #{look_for}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+  
+  def route_resources(resource_list)
+    look_for = "  map.resources #{resource_list}\n".gsub(/[\[\]]/, '\\\\\0')
+    logger.route "map.resources #{resource_list} #{look_for}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end  
+  
+  def route_name(name, path, route_options = {})
+    look_for =   "\n  map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    logger.route "map.#{name} '#{path}',     :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    unless options[:pretend]
+      gsub_file    'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+  
+  def insert_into(file, line)
+    logger.remove "#{line} from #{file}"
+    unless options[:pretend]
+      gsub_file file, "\n  #{line}", ''
+    end
+  end
+end
+
+Rails::Generator::Commands::List.class_eval do
+  def route_resource(resources_list)
+    logger.route "map.resource #{resource_list}"
+  end
+  
+  def route_resources(resources_list)
+    logger.route "map.resource #{resource_list}"
+  end  
+  
+  def route_name(name, path, options = {})
+    logger.route "map.#{name} '#{path}', :controller => '{options[:controller]}', :action => '#{options[:action]}'"
+  end
+  
+  def insert_into(file, line)
+    logger.insert "#{line} into #{file}"
+  end
+end