README.md in devise-multi_email-1.0.5 vs README.md in devise-multi_email-2.0.0
- old
+ new
@@ -1,32 +1,32 @@
# Devise::MultiEmail [](https://travis-ci.org/allenwq/devise-multi_email) [](https://coveralls.io/github/allenwq/devise-multi_email?branch=master)
-Let [devise](https://github.com/plataformatec/devise) support multilpe emails, it allows you to:
+Letting [Devise](https://github.com/plataformatec/devise) support multiple emails, allows you to:
- Login with multiple emails
- Send confirmations to multiple emails
- Recover the password with any of the emails
-- Validations for multiple emails
+- Validations for multiple emails
-`:multi_email_authenticatable`, `:multi_email_confirmable` and `:multi_email_validatable` are provided by devise-multi_email.
+`:multi_email_authenticatable`, `:multi_email_confirmable` and `:multi_email_validatable` are provided by _devise-multi_email_.
## Getting Started
-Add this line to your application's Gemfile, devise-multi_email has been tested with devise 4.0 and rails 4.2:
+Add this line to your application's `Gemfile`, _devise-multi_email_ has been tested with Devise 4.0 and rails 4.2:
```ruby
gem 'devise-multi_email'
```
-Suppose you have already setup devise, your `User` model might look like this:
+Suppose you have already setup Devise, your `User` model might look like this:
```ruby
class User < ActiveRecord::Base
devise :database_authenticatable, :registerable
end
```
-In order to let your `User` support multiple emails, with `devise-multi_email` what you need to do is just:
+In order to let your `User` support multiple emails, with _devise-multi_email_ what you need to do is just:
```ruby
class User < ActiveRecord::Base
has_many :emails
@@ -37,73 +37,125 @@
class Email < ActiveRecord::Base
belongs_to :user
end
```
-Note that `:email` column should be moved from users table to the emails table, and a new `primary` boolean column should be added to the emails table (so that all the emails will be sent to the primary email, and `user.email` will give you the primary email address). Your emails table's migration should look like:
+Note that the `:email` column should be moved from `users` table to the `emails` table, and a new `primary` boolean column should be added to the `emails` table (so that all the emails will be sent to the primary email, and `user.email` will give you the primary email address). Your `emails` table's migration should look like:
+
```ruby
create_table :emails do |t|
t.integer :user_id
t.string :email
t.boolean :primary
end
```
+### Configure custom association names
+
+You may not want to use the association `user.emails` or `email.users`. You can customize the name of the associations used. Add your custom configurations to an initializer file such as `config/initializers/devise-multi_email.rb`.
+
+_Note: model classes are inferred from the associations._
+
+```ruby
+Devise::MultiEmail.configure do |config|
+ # Default is :user for Email model
+ config.parent_association_name = :team
+ # Default is :emails for parent (e.g. User) model
+ config.emails_association_name = :email_addresses
+ # For backwards-compatibility, specify :primary_email_record
+ # Default is :primary_email
+ config.primary_email_method_name = :primary_email_record
+end
+
+# Example use of custom association names
+team = Team.first
+emails = team.email_addresses
+
+email = EmailAddress.first
+team = email.team
+```
+
## Confirmable with multiple emails
-Sending different confirmaitons to different emails is supported. What you need to do is:
+Sending separate confirmations to each email is supported. What you need to do is:
+
Declare `devise :multi_email_confirmable` in your `User` model:
+
```ruby
class User < ActiveRecord::Base
has_many :emails
- # You should not declare :confiramble and :multi_email_confirmable at the same time.
+ # You should not declare :confirmable and :multi_email_confirmable at the same time.
devise :multi_email_authenticatable, :registerable, :multi_email_confirmable
end
```
-Add `:confirmation_token`, `:confirmed_at` and `:confirmation_sent_at` to your emails table:
+Add `:confirmation_token`, `:confirmed_at` and `:confirmation_sent_at` to your `emails` table:
+
```ruby
create_table :emails do |t|
t.integer :user_id
t.string :email
t.boolean :primary, default: false
## Confirmable
- t.string :confirmation_token
+ t.string :unconfirmed_email
+ t.string :confirmation_token
t.datetime :confirmed_at
t.datetime :confirmation_sent_at
end
```
-Then all the methods in devise confirmable are avalible in your `Email` model. You can do `Email#send_confirmation_instructions` for each of your email. And `User#send_confirmation_instructions` will be delegated to the primary email.
+Then all the methods in Devise confirmable are available in your `Email` model. You can do `email#send_confirmation_instructions` for each of your email. And `user#send_confirmation_instructions` will be delegated to the primary email.
## Validatable with multiple emails
-Declare `devise :multi_email_validatable` in the user model, then all the user emails will be validated:
+Declare `devise :multi_email_validatable` in the `User` model, then all the user emails will be validated:
+
```ruby
class User < ActiveRecord::Base
has_many :emails
# You should not declare :validatable and :multi_email_validatable at the same time.
devise :multi_email_authenticatable, :registerable, :multi_email_validatable
end
```
+You can find the detailed configurations in the [rails 5 example app](https://github.com/allenwq/devise-multi_email/tree/master/examples/rails5_app).
+
+## ActiveJob Integration
+
+The [Devise README](https://github.com/plataformatec/devise#activejob-integration) describes how to use ActiveJob to deliver emails in the background. Normally you would place the following code in your `User` model, however when using _devise-multi_email_ you should place this in the `Email` model.
+
+```ruby
+# models/email.rb
+def send_devise_notification(notification, *args)
+ devise_mailer.send(notification, self, *args).deliver_later
+end
+```
+
## What's more
-The gem works with all other devise modules just as normal, you don't need to add the `multi_email` prefix.
+The gem works with all other Devise modules as expected -- you don't need to add the "multi_email" prefix.
+
```ruby
- devise :multi_email_authenticatable, :multi_email_confirmable, :multi_email_validatable, :lockable,
+class User < ActiveRecord::Base
+ devise :multi_email_authenticatable, :multi_email_confirmable, :multi_email_validatable, :lockable,
:recoverable, :registerable, :rememberable, :timeoutable, :trackable
+end
```
## Issues
-You need to implement add/delete emails for a user as well as set/unset primary email.
-You can do `email.send_confirmation_instructions` for every email, but you also need to handle this logic in some place(excpet for the primary email). e.g. After a new email was added by a user, you might want to provide some buttons to allow user to resend confirmation instrucitons for that email.
+You need to implement add/delete emails for a user as well as set/unset "primary" for each email.
+You can do `email.send_confirmation_instructions` for each email individually, but you need to handle that logic in some place (except for the primary email, which is handled by Devise by default). e.g. After a new email was added by a user, you might want to provide some buttons in the view to allow users to resend confirmation instructions for that email.
+
+## Wiki
+
+[Migrating exiting user records](https://github.com/allenwq/devise-multi_email/wiki/Migrating-existing-user-records)
+
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
@@ -114,6 +166,5 @@
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-