Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Deprecate :all.

  • Loading branch information...
commit efc0ae230a43a0c7aa0ed11619af4fc8f4a9fef3 1 parent f075a6b
@josevalim josevalim authored
View
68 README.rdoc
@@ -7,7 +7,7 @@ Devise is a flexible authentication solution for Rails based on Warden. It:
* Allows you to have multiple roles (or models/scopes) signed in at the same time;
* Is based on a modularity concept: use just what you really need.
-Right now it's composed of six modules included by default when you invoke "devise :all" in your models:
+Right now it's composed of nine modules:
* Authenticatable: responsible for encrypting password and validating authenticity of a user while signing in.
* Confirmable: responsible for verifying whether an account is already confirmed to sign in, and to send emails with confirmation instructions.
@@ -15,12 +15,9 @@ Right now it's composed of six modules included by default when you invoke "devi
* Rememberable: manages generating and clearing token for remember the user from a saved cookie.
* Trackable: tracks sign in count, timestamps and ip.
* Validatable: creates all needed validations for email and password. It's totally optional, so you're able to to customize validations by yourself.
-
-And it also includes the optional modules:
-
-* Activatable: if you need to activate accounts by other means, which are not through confirmation, use this module.
* Timeoutable: expires sessions without activity in a certain period of time.
* Lockable: takes care of locking an account based on the number of failed sign in attempts. Handles unlock via expire and email.
+* Activatable: if you need to activate accounts by other means, which are not through confirmation, use this module.
There's an example application using Devise at http://github.com/plataformatec/devise_example .
@@ -55,11 +52,17 @@ And you're ready to go. The generator will install an initializer which describe
== Basic Usage
-This is a walkthrough with all steps you need to setup a devise resource, including model, migration, route files, and optional configuration. You can also check out the *Generators* section below to help you start.
+This is a walkthrough with all steps you need to setup a devise resource, including model, migration, route files, and optional configuration. You MUST also check out the *Generators* section below to help you start.
Devise must be set up within the model (or models) you want to use, and devise routes must be created inside your config/routes.rb file.
-We're assuming here you want a User model with the six default modules. First of all, you have to setup a migration with the following:
+We're assuming here you want a User model with some modules, as outlined below:
+
+ class User < ActiveRecord::Base
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable
+ end
+
+After you choose which modules to use, you need to setup your migrations. Luckily, devise has some helpers to save you from this boring work:
create_table :users do |t|
t.authenticatable
@@ -70,31 +73,9 @@ We're assuming here you want a User model with the six default modules. First of
t.timestamps
end
-Now let's setup a User model adding the devise line:
-
- class User < ActiveRecord::Base
- devise :all
- end
-
-This will include the six default modules outlined at the beginning. You can exclude and remove any module at will:
-
- # Include timeout configuration
- devise :all, :timeoutable
-
- # Remove validations
- devise :all, :except => :validatable
-
Remember that Devise don't rely on _attr_accessible_ or _attr_protected_ inside its modules, so be sure to setup what attributes are accessible or protected in your model.
-== Model configuration
-
-In addition to :except, you can provide :pepper, :stretches, :encryptor, :authentication_keys, :confirm_within, :remember_for and :timeout as options to devise method.
-
-All those options are described in "config/initializers/devise.rb", which is generated when you invoke `ruby script/generate devise_install` in your application root.
-
-== Routes
-
-The next step after setting up your model is to configure your routes for devise. You do this by opening up your config/routes.rb and adding:
+The next setup after setting up your model is to configure your routes. You do this by opening up your config/routes.rb and adding:
map.devise_for :users
@@ -106,6 +87,8 @@ There are also some options available for configuring your routes, as :class_nam
Be sure to check devise_for documentation for detailed description.
+After this steps, run your migrations, and you are ready to go! But don't finish reading, we still have a lot to tell you:
+
== Controller filters and helpers
Devise is gonna create some helpers to use inside your controllers and views. To setup a controller that needs user authentication, just add this before_filter:
@@ -124,7 +107,7 @@ You have also access to the session for this scope:
user_session
-After signing in a user, confirming it's account or updating it's password, devise will look for a scoped root path to redirect. Example: For a :user resource, it will use user_root_path if it exists, otherwise default root_path will be used. To do it so, you need to create e default root inside your routes for your application:
+After signing in a user, confirming it's account or updating it's password, devise will look for a scoped root path to redirect. Example: For a :user resource, it will use user_root_path if it exists, otherwise default root_path will be used. This means that you need to set the root inside your routes:
map.root :controller => 'home'
@@ -134,10 +117,6 @@ Finally, you also need to setup default url options for the mailer in each envir
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
-== Views
-
-By default devise will use the same views for all scopes/roles you have. But what if you need so different views to each of them? Devise also has an easy way to accomplish it: just setup config,scoped_views to true inside your devise config file, and you will be able to have views based on scope like 'sessions/users/new' and 'sessions/admin/new'. If no view is found within the scope, Devise will fallback to the default view.
-
== Tidying up
Devise let's you setup as many roles as you want, so let's say you already have this User model and also want an Admin model with just authentication, trackable, lockable and timeoutable stuff and none of confirmation or password recovery. Just follow the same steps:
@@ -175,11 +154,23 @@ This will generate an initializer, with a description of all configuration value
A model configured with all devise modules and attr_accessible for default fields will be created. The generator will also create the migration and configure your routes for devise.
-You can also copy devise views to your application, being able to modify them based on your needs. To do it so, run the following command:
+== Model configuration
+
+The devise method in your models also accept some options to configure its modules. For example, you can chose which encryptor to use in authenticatable:
+
+ devise :authenticatable, :confirmable, :recoverable, :encryptor => :bcrypt
+
+Besides :encryptor, you can provide :pepper, :stretches, :confirm_within, :remember_for, :timeout, :unlock_in and others. All those are describer in the initializer created when you invoke the devise_install generator describer above.
+
+== Views
+
+Since devise is an engine, it has all default views inside the gem. They are good to get you started, but you will want to customize them at some point. And Devise has a generator to make copy them all to your application:
ruby script/generate devise_views
-This is gonna copy all session, password, confirmation and mailer views to your app/views folder.
+By default Devise will use the same views for all roles you have. But what if you need so different views to each of them? Devise also has an easy way to accomplish it: just setup config.scoped_views to true inside "config/initializers/devise.rb".
+
+After doing so you will be able to have views based on the scope like 'sessions/users/new' and 'sessions/admin/new'. If no view is found within the scope, Devise will fallback to the default view.
== I18n
@@ -236,8 +227,7 @@ Devise implements encryption strategies for Clearance, Authlogic and Restful-Aut
== Other ORMs
-Devise was made to work from scratch with ActiveRecord. However it currently supports DataMapper and MongoMapper as well.
-To use it, just set Devise.orm or configure it in the initialization file (which is created with devise_install).
+Devise supports both ActiveRecord (default) and MongoMapper, and has experimental Datamapper supports (in a sense that Devise test suite does not run completely with Datamapper). To choose other ORM, you just need to configure it in the initializer file.
== TODO
View
4 generators/devise/templates/migration.rb
@@ -6,7 +6,7 @@ def self.up
t.recoverable
t.rememberable
t.trackable
- t.lockable
+ # t.lockable
t.timestamps
end
@@ -14,7 +14,7 @@ def self.up
add_index :<%= table_name %>, :email, :unique => true
add_index :<%= table_name %>, :confirmation_token, :unique => true
add_index :<%= table_name %>, :reset_password_token, :unique => true
- add_index :<%= table_name %>, :unlock_token, :unique => true
+ # add_index :<%= table_name %>, :unlock_token, :unique => true
end
def self.down
View
5 generators/devise/templates/model.rb
@@ -1,5 +1,8 @@
class <%= class_name %> < ActiveRecord::Base
- devise :all
+ # Include default devise modules.
+ # Others available are :lockable, :timeoutable and :activatable.
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable
+
# Setup accessible (or protected) attributes for your model
attr_accessible :email, :password, :password_confirmation
end
View
33 generators/devise_install/templates/devise.rb
@@ -1,18 +1,10 @@
# Use this hook to configure devise mailer, warden hooks and so forth. The first
# four configuration values can also be set straight in your models.
Devise.setup do |config|
- # Configure Devise modules used by default. You should always set this value
- # because if Devise adds a new strategy, it won't be added to your application
- # by default, unless you configure it here.
- #
- # Remember that Devise includes other modules on its own (like :activatable
- # and :timeoutable) which are not included here and also plugins. So be sure
- # to check the docs for a complete set.
- config.all = [:authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable]
-
# Configure the e-mail address which will be shown in DeviseMailer.
config.mailer_sender = "please-change-me@config-initializers-devise.com"
+ # ==> Configuration for :authenticatable
# Invoke `rake secret` and use the printed value to setup a pepper to generate
# the encrypted password. By default no pepper is used.
# config.pepper = "rake secret output"
@@ -34,26 +26,21 @@
# session. If you need permissions, you should implement that in a before filter.
# config.authentication_keys = [ :email ]
+ # ==> Configuration for :confirmable
# The time you want give to your user to confirm his account. During this time
# he will be able to access your application without confirming. Default is nil.
# config.confirm_within = 2.days
+ # ==> Configuration for :rememberable
# The time the user will be remembered without asking for credentials again.
# config.remember_for = 2.weeks
+ # ==> Configuration for :timeoutable
# The time you want to timeout the user session without activity. After this
# time the user will be asked for credentials again.
# config.timeout_in = 10.minutes
- # Load and configure the ORM. Supports :active_record, :data_mapper and :mongo_mapper.
- # require 'devise/orm/mongo_mapper'
- # config.orm = :mongo_mapper
-
- # Turn scoped views on. Before rendering "sessions/new", it will first check for
- # "sessions/users/new". It's turned off by default because it's slower if you
- # are using only default views.
- # config.scoped_views = true
-
+ # ==> Configuration for :lockable
# Number of authentication tries before locking an account.
# config.maximum_attempts = 20
@@ -66,6 +53,16 @@
# Time interval to unlock the account if :time is enabled as unlock_strategy.
# config.unlock_in = 1.hour
+ # ==> General configuration
+ # Load and configure the ORM. Supports :active_record, :data_mapper and :mongo_mapper.
+ # require 'devise/orm/mongo_mapper'
+ # config.orm = :mongo_mapper
+
+ # Turn scoped views on. Before rendering "sessions/new", it will first check for
+ # "sessions/users/new". It's turned off by default because it's slower if you
+ # are using only default views.
+ # config.scoped_views = true
+
# By default, devise detects the role accessed based on the url. So whenever
# accessing "/users/sign_in", it knows you are accessing an User. This makes
# routes as "/sign_in" not possible, unless you tell Devise to use the default
View
4 lib/devise.rb
@@ -94,9 +94,9 @@ module Orm
mattr_accessor :orm
@@orm = :active_record
- # Configure default options used in :all.
+ # TODO Remove
mattr_accessor :all
- @@all = Devise::ALL.dup
+ @@all = []
# Tells if devise should apply the schema in ORMs where devise declaration
# and schema belongs to the same class (as Datamapper and MongoMapper).
View
37 lib/devise/models.rb
@@ -47,43 +47,24 @@ def #{accessor}=(value)
end
end
- # Shortcut method for including all devise modules inside your model.
- # You can give some extra options while declaring devise in your model:
+ # Include the chosen devise modules in your model:
#
- # * except: convenient option that allows you to add all devise modules,
- # removing only the modules you setup here:
- #
- # devise :all, :except => :rememberable
+ # devise :authenticatable, :confirmable, :recoverable
#
# You can also give the following configuration values in a hash: :pepper,
# :stretches, :confirm_within and :remember_for. Please check your Devise
# initialiazer for a complete description on those values.
#
- # Examples:
- #
- # # include only authenticatable module
- # devise :authenticatable
- #
- # # include authenticatable + confirmable modules
- # devise :authenticatable, :confirmable
- #
- # # include authenticatable + recoverable modules
- # devise :authenticatable, :recoverable
- #
- # # include authenticatable + rememberable + validatable modules
- # devise :authenticatable, :rememberable, :validatable
- #
- # # shortcut to include all available modules
- # devise :all
- #
- # # include all except recoverable
- # devise :all, :except => :recoverable
- #
def devise(*modules)
raise "You need to give at least one Devise module" if modules.empty?
-
options = modules.extract_options!
- modules += Devise.all if modules.delete(:all)
+
+ # TODO Remove me
+ if modules.delete(:all)
+ ActiveSupport::Deprecation.warn "devise :all is deprecated. List your modules instead", caller
+ modules += Devise.all
+ end
+
modules -= Array(options.delete(:except))
modules = Devise::ALL & modules.uniq
View
2  test/rails_app/app/active_record/account.rb
@@ -1,5 +1,5 @@
class Account < ActiveRecord::Base
- devise :all
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable
def self.find_for_authentication(conditions)
nil
View
2  test/rails_app/app/active_record/admin.rb
@@ -1,5 +1,5 @@
class Admin < ActiveRecord::Base
- devise :all, :timeoutable, :except => [:recoverable, :confirmable, :rememberable, :validatable, :trackable, :lockable]
+ devise :authenticatable, :timeoutable
def self.find_for_authentication(conditions)
last(:conditions => conditions)
View
3  test/rails_app/app/active_record/user.rb
@@ -1,4 +1,5 @@
class User < ActiveRecord::Base
- devise :all, :timeoutable, :lockable
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable,
+ :validatable, :timeoutable, :lockable
attr_accessible :username, :email, :password, :password_confirmation
end
View
2  test/rails_app/app/mongo_mapper/account.rb
@@ -1,7 +1,7 @@
class Account
include MongoMapper::Document
- devise :all
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable
def self.find_for_authentication(conditions)
nil
View
2  test/rails_app/app/mongo_mapper/admin.rb
@@ -1,7 +1,7 @@
class Admin
include MongoMapper::Document
- devise :all, :timeoutable, :except => [:recoverable, :confirmable, :rememberable, :validatable, :trackable]
+ devise :authenticatable, :timeoutable
def self.find_for_authentication(conditions)
last(:conditions => conditions, :order => "email")
View
3  test/rails_app/app/mongo_mapper/user.rb
@@ -1,6 +1,7 @@
class User
include MongoMapper::Document
key :created_at, DateTime
- devise :all, :timeoutable, :lockable
+ devise :authenticatable, :confirmable, :recoverable, :rememberable, :trackable,
+ :validatable, :timeoutable, :lockable
# attr_accessible :username, :email, :password, :password_confirmation
end
View
11 test/rails_app/config/initializers/devise.rb
@@ -1,15 +1,6 @@
# Use this hook to configure devise mailer, warden hooks and so forth. The first
# four configuration values can also be set straight in your models.
Devise.setup do |config|
- # Configure Devise modules used by default. You should always set this value
- # because if Devise adds a new strategy, it won't be added to your application
- # by default, unless you configure it here.
- #
- # Remember that Devise includes other modules on its own (like :activatable
- # and :timeoutable) which are not included here and also plugins. So be sure
- # to check the docs for a complete set.
- config.all = [:authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable]
-
# Invoke `rake secret` and use the printed value to setup a pepper to generate
# the encrypted password. By default no pepper is used.
# config.pepper = "rake secret output"
@@ -43,7 +34,7 @@
# config.timeout_in = 10.minutes
# Configure the e-mail address which will be shown in DeviseMailer.
- # config.mailer_sender = "foo.bar@yourapp.com"
+ config.mailer_sender = "please-change-me-omg@yourapp.com"
# Load and configure the ORM. Supports :active_record, :data_mapper and :mongo_mapper.
require "devise/orm/#{DEVISE_ORM}"
View
8 test/rails_app/config/routes.rb
@@ -1,9 +1,11 @@
ActionController::Routing::Routes.draw do |map|
map.devise_for :users
map.devise_for :admin, :as => 'admin_area'
- map.devise_for :accounts, :path_names => {
- :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification'
- }, :scope => 'manager', :path_prefix => '/:locale', :requirements => { :extra => 'value' }
+ map.devise_for :accounts, :scope => 'manager', :path_prefix => '/:locale',
+ :class_name => "User", :requirements => { :extra => 'value' }, :path_names => {
+ :sign_in => 'login', :sign_out => 'logout', :password => 'secret',
+ :confirmation => 'verification', :unlock => 'unblock'
+ }
map.resources :users, :only => [:index], :member => { :expire => :get }
map.resources :admins, :only => :index
View
5 test/routes_test.rb
@@ -67,4 +67,9 @@ class MapRoutingTest < ActionController::TestCase
test 'map account with custom path name for confirmation' do
assert_recognizes({:controller => 'confirmations', :action => 'new', :locale => 'en', :extra => 'value'}, '/en/accounts/verification/new')
end
+
+ test 'map account with custom path name for unlock' do
+ assert_recognizes({:controller => 'unlocks', :action => 'new', :locale => 'en', :extra => 'value'}, '/en/accounts/unblock/new')
+ end
+
end
Please sign in to comment.
Something went wrong with that request. Please try again.