From a789f08d3bd110c43964c74d01b0032714d4dca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Tue, 5 Jan 2010 16:01:16 +0100 Subject: [PATCH] Cleaning up README to be more compatible with the latest stuff. --- CHANGELOG.rdoc | 6 +++ README.rdoc | 51 ++++++++----------- app/models/devise_mailer.rb | 13 +---- generators/devise/templates/README | 22 ++++---- lib/devise.rb | 10 ++-- lib/devise/models/timeoutable.rb | 4 +- test/devise_test.rb | 9 ---- .../mailers/confirmation_instructions_test.rb | 2 +- .../reset_password_instructions_test.rb | 2 +- 9 files changed, 48 insertions(+), 71 deletions(-) diff --git a/CHANGELOG.rdoc b/CHANGELOG.rdoc index bcc0aa407e..6720238281 100644 --- a/CHANGELOG.rdoc +++ b/CHANGELOG.rdoc @@ -1,3 +1,9 @@ +* enhancements + * Warden 0.8.0 compatibility + +* deprecation + * Removed DeviseMailer.sender + == 0.7.5 * enhancements diff --git a/README.rdoc b/README.rdoc index 2115263a58..726648eaf9 100644 --- a/README.rdoc +++ b/README.rdoc @@ -7,22 +7,25 @@ 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 seven mainly modules: +Right now it's composed of six modules included by default when you invoke "devise :all" in your models: * 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. * Recoverable: takes care of reseting the user password and send reset instructions. * Rememberable: manages generating and clearing token for remember the user from a saved cookie. -* 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. * 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. + There's an example application using Devise at http://github.com/plataformatec/devise_example . == Dependencies -Devise is based on Warden (http://github.com/hassox/warden), a Rack Authentication Framework so you need to install it as a gem. Please ensure you have it installed in order to use devise (see instalation below). +Devise is based on Warden (http://github.com/hassox/warden), a Rack Authentication Framework so you need to install it as a gem. Please ensure you have it installed in order to use devise (see installation below). == Installation @@ -53,7 +56,7 @@ And you're ready to go. The generator will install an initializer which describe 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. -Devise must be set up within the model (or models) you want to use, and devise routes must be created inside your routes.rb file. +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. First of all you have to setup a migration with the following fields: @@ -62,6 +65,7 @@ We're assuming here you want a User model. First of all you have to setup a migr t.confirmable t.recoverable t.rememberable + t.trackable t.timestamps end @@ -71,35 +75,21 @@ You may also want to add some indexes to improve performance: add_index :your_table, :confirmation_token # for confirmable add_index :your_table, :reset_password_token # for recoverable -Now let's setup a User model adding the devise line to have your authentication working: +Now let's setup a User model adding the devise line: class User < ActiveRecord::Base - devise :authenticatable + devise :all end -This line adds devise authenticatable inside your User class. 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. - -You could also include the other devise modules as below: - - # Include only authenticatable stuff - devise :authenticatable - - # Include authenticatable + confirmable - devise :authenticatable, :confirmable - - # Include authenticatable + recoverable + rememberable - devise :authenticatable, :recoverable, :rememberable - - # Include authenticatable + timeoutable - devise :authenticatable, :timeoutable +This will include the six default modules outlined at the beginning. You can exclude and remove any module at will: - # Include all of them - devise :all + # Include timeout configuration + devise :all, :timeoutable - # Include all except recoverable - devise :all, :except => :recoverable + # Remove validations + devise :all, :except => :validatable -Note that validations aren't added by default, so you're able to customize it. In order to have automatic validations working just include :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 @@ -151,19 +141,20 @@ Finally, if you are using confirmable or recoverable, you also need to setup def == 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 :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. +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 the same authentication stuff, but not confirmation or password recovery. Just follow the same steps: +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 and timeoutable stuff and none of confirmation or password recovery. Just follow the same steps: # Create a migration with the required fields create_table :admins do |t| t.authenticatable + t.trackable end # Inside your Admin model - devise :authenticatable, :validatable + devise :authenticatable, :trackable, :timeoutable # Inside your routes map.devise_for :admin diff --git a/app/models/devise_mailer.rb b/app/models/devise_mailer.rb index 7bc91a9f8d..8647203e6d 100644 --- a/app/models/devise_mailer.rb +++ b/app/models/devise_mailer.rb @@ -1,16 +1,5 @@ class DeviseMailer < ::ActionMailer::Base - # Sets who is sending the e-mail - def self.sender=(value) - @@sender = value - end - - # Reads who is sending the e-mail - def self.sender - @@sender - end - self.sender = nil - # Deliver confirmation instructions when the user is created or its email is # updated, and also when confirmation is manually requested def confirmation_instructions(record) @@ -30,7 +19,7 @@ def setup_mail(record, key) raise "Invalid devise resource #{record}" unless mapping subject translate(mapping, key) - from self.class.sender + from Devise.mailer_sender recipients record.email sent_on Time.now content_type 'text/html' diff --git a/generators/devise/templates/README b/generators/devise/templates/README index c748d5fac0..2581b34b8e 100644 --- a/generators/devise/templates/README +++ b/generators/devise/templates/README @@ -1,22 +1,22 @@ -================================================================================ +=============================================================================== Some setup you must do manually if you haven't yet: -1. Setup defaut url options for your specific environment. Here is an example of development environment: + 1. Run devise install generator: - config.action_mailer.default_url_options = { :host => 'localhost:3000' } + ruby script/generate devise_install -It's a Rails required configuration. In production it must be the actual host your application is deployed to. + 2. Setup defaut url options for your specific environment. Here is an + example of development environment: -2. Setup default sender for mails. In config/environment.rb: + config.action_mailer.default_url_options = { :host => 'localhost:3000' } - DeviseMailer.sender = "test@example.com" + This is a required Rails configuration. In production is must be the + actual host of your application -You can also configure this value by running script/generate devise_install and setting config.mailer_sender, + 3. Ensure you have defined root_url to *something* in your config/routes.rb: -3. Ensure you have defined root_url to *something* in your config/routes.rb: + map.root :controller => 'home' - map.root :controller => 'home' - -================================================================================ +=============================================================================== diff --git a/lib/devise.rb b/lib/devise.rb index bcc9ea4cc5..8c64901be7 100644 --- a/lib/devise.rb +++ b/lib/devise.rb @@ -107,6 +107,10 @@ module Orm mattr_accessor :default_scope @@default_scope = nil + # Address which sends Devise e-mails + mattr_accessor :mailer_sender + @@mailer_sender + class << self # Default way to setup Devise. Run script/generate devise_install to create # a fresh initializer with all configuration values. @@ -114,12 +118,6 @@ def setup yield self end - # Sets the sender in DeviseMailer. - def mailer_sender=(value) - DeviseMailer.sender = value - end - alias :sender= :mailer_sender= - # Sets warden configuration using a block that will be invoked on warden # initialization. # diff --git a/lib/devise/models/timeoutable.rb b/lib/devise/models/timeoutable.rb index c10624236b..fd29d1210c 100644 --- a/lib/devise/models/timeoutable.rb +++ b/lib/devise/models/timeoutable.rb @@ -8,11 +8,13 @@ module Models # will be asked for credentials again, it means, he/she will be redirected # to the sign in page. # + # In order to use timeoutable, you need to use trackable. So don't forget + # to invoke trackable in your migrations. + # # Configuration: # # timeout: the time you want to timeout the user session without activity. module Timeoutable - def self.included(base) base.extend ClassMethods end diff --git a/test/devise_test.rb b/test/devise_test.rb index 24503a6e5b..66abfe0b9f 100644 --- a/test/devise_test.rb +++ b/test/devise_test.rb @@ -7,15 +7,6 @@ def self.clean_warden_config! end class DeviseTest < ActiveSupport::TestCase - - test 'DeviseMailer.sender can be configured through Devise' do - swap DeviseMailer, :sender => "foo@bar" do - assert_equal "foo@bar", DeviseMailer.sender - Devise.mailer_sender = "bar@foo" - assert_equal "bar@foo", DeviseMailer.sender - end - end - test 'model options can be configured through Devise' do swap Devise, :confirm_within => 113, :pepper => "foo" do assert_equal 113, Devise.confirm_within diff --git a/test/mailers/confirmation_instructions_test.rb b/test/mailers/confirmation_instructions_test.rb index 4eb3cb0dd7..c69d278967 100644 --- a/test/mailers/confirmation_instructions_test.rb +++ b/test/mailers/confirmation_instructions_test.rb @@ -4,7 +4,7 @@ class ConfirmationInstructionsTest < ActionMailer::TestCase def setup setup_mailer - DeviseMailer.sender = 'test@example.com' + Devise.mailer_sender = 'test@example.com' end def user diff --git a/test/mailers/reset_password_instructions_test.rb b/test/mailers/reset_password_instructions_test.rb index 5931c7a063..f7f5d59757 100644 --- a/test/mailers/reset_password_instructions_test.rb +++ b/test/mailers/reset_password_instructions_test.rb @@ -4,7 +4,7 @@ class ResetPasswordInstructionsTest < ActionMailer::TestCase def setup setup_mailer - DeviseMailer.sender = 'test@example.com' + Devise.mailer_sender = 'test@example.com' end def user