kotovalexarian-likes-github/heartcombo--devise
1
0
Fork 0
mirror of https://github.com/heartcombo/devise.git synced 2022-11-09 12:18:31 -05:00
Code Releases Activity

Update README.md

Browse source 
The updates are:

* Indicate that it is possible to pass a block to `super` to add custom
  behaviour to some Devise controller actions without completely
  overriding them.

* Move mailer configuration out of the section "Controller filters and
  helpers".

* Consistently use Ruby 1.9's hash syntax, highlight code and capitalize
  "Devise".

* Wording improvements
This commit is contained in:
Guilherme Simoes 2014-02-14 18:00:26 +00:00
parent 93bdee2640
commit e18b822567
1 changed files with 51 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
README.md
View file

@ -110,9 +110,15 @@ The generator will install an initializer which describes ALL Devise's configura
rails generate devise MODEL
```
Replace MODEL by the class name used for the applications users, it's frequently `User` but could also be `Admin`. This will create a model (if one does not exist) and configure it with default Devise modules. Next, you'll usually run `rake db:migrate` as the generator will have created a migration file (if your ORM supports them). This generator also configures your config/routes.rb file to point to the Devise controller.
Replace MODEL by the class name used for the applications users, it's frequently `User` but could also be `Admin`. This will create a model (if one does not exist) and configure it with default Devise modules. Next, you'll usually run `rake db:migrate` as the generator will have created a migration file (if your ORM supports them). This generator also configures your `config/routes.rb` file to point to the Devise controller.
Note that you should re-start your app here if you've already started it. Otherwise you'll run into strange errors like users being unable to login and the route helpers being undefined.
Next, you need to set up the default url options for the Devise mailer in each environment. Here is a possible configuration for `config/environments/development.rb`:
```ruby
config.action_mailer.default_url_options = { host: 'localhost:3000' }
```
You should restart your application after changing Devise's configuration options. Otherwise you'll run into strange errors like users being unable to login and route helpers being undefined.
### Controller filters and helpers
@ -140,21 +146,15 @@ You can access the session for this scope:
user_session
```
After signing in a user, confirming the account or updating the 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:
After signing in a user, confirming the account or updating the password, Devise will look for a scoped root path to redirect. For instance, for a `:user` resource, the `user_root_path` will be used if it exists, otherwise the default `root_path` will be used. This means that you need to set the root inside your routes:
```ruby
root to: "home#index"
```
You can also overwrite `after_sign_in_path_for` and `after_sign_out_path_for` to customize your redirect hooks.
You can also override `after_sign_in_path_for` and `after_sign_out_path_for` to customize your redirect hooks.
Finally, you need to set up default url options for the mailer in each environment. Here is the configuration for "config/environments/development.rb":
```ruby
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
```
Notice that if your devise model is not called "user" but "member", then the helpers you should use are:
Notice that if your Devise model is called `Member` instead of `User`, for example, then the helpers available are:
```ruby
before_filter :authenticate_member!
@ -168,13 +168,13 @@ member_session
### Configuring Models
The devise method in your models also accepts some options to configure its modules. For example, you can choose the cost of the encryption algorithm with:
The Devise method in your models also accepts some options to configure its modules. For example, you can choose the cost of the encryption algorithm with:
```ruby
devise :database_authenticatable, :registerable, :confirmable, :recoverable, :stretches => 20
devise :database_authenticatable, :registerable, :confirmable, :recoverable, stretches: 20
```
Besides :stretches, you can define :pepper, :encryptor, :confirm_within, :remember_for, :timeout_in, :unlock_in and other values. For details, see the initializer file that was created when you invoked the "devise:install" generator described above.
Besides `:stretches`, you can define `:pepper`, `:encryptor`, `:confirm_within`, `:remember_for`, `:timeout_in`, `:unlock_in` among other options. For more details, see the initializer file that was created when you invoked the "devise:install" generator described above.
### Strong Parameters
@ -246,9 +246,9 @@ Since Devise is an engine, all its views are packaged inside the gem. These view
rails generate devise:views
```
If you have more than one Devise model in your application (such as "User" and "Admin"), you will notice that Devise uses the same views for all models. Fortunately, Devise offers an easy way to customize views. All you need to do is set "config.scoped_views = true" inside "config/initializers/devise.rb".
If you have more than one Devise model in your application (such as `User` and `Admin`), you will notice that Devise uses the same views for all models. Fortunately, Devise offers an easy way to customize views. All you need to do is set `config.scoped_views = true` inside the `config/initializers/devise.rb` file.
After doing so, you will be able to have views based on the role like "users/sessions/new" and "admins/sessions/new". If no view is found within the scope, Devise will use the default view at "devise/sessions/new". You can also use the generator to generate scoped views:
After doing so, you will be able to have views based on the role like `users/sessions/new` and `admins/sessions/new`. If no view is found within the scope, Devise will use the default view at `devise/sessions/new`. You can also use the generator to generate scoped views:
```console
rails generate devise:views users
@ -270,19 +270,45 @@ If the customization at the views level is not enough, you can customize each co
2. Tell the router to use this controller:
```ruby
devise_for :admins, :controllers => { :sessions => "admins/sessions" }
devise_for :admins, controllers: { sessions: "admins/sessions" }
```
3. And since we changed the controller, it won't use the `"devise/sessions"` views, so remember to copy `"devise/sessions"` to `"admins/sessions"`.
3. Copy the views from `devise/sessions` to `admins/sessions`. Since the controller was changed, it won't use the default views located in `devise/sessions`.
Remember that Devise uses flash messages to let users know if sign in was successful or failed. Devise expects your application to call `"flash[:notice]"` and `"flash[:alert]"` as appropriate. Do not print the entire flash hash, print specific keys or at least remove the `:timedout` key from the hash as Devise adds this key in some circumstances, this key is not meant for display.
4. Finally, change or extend the desired controller actions.
You can completely override a controller action:
```ruby
class Admins::SessionsController < Devise::SessionsController
def create
# custom sign-in code
end
end
```
Or you can simply add new behaviour to it:
```ruby
class Admins::SessionsController < Devise::SessionsController
def create
super do |resource|
BackgroundWorker.trigger(resource)
end
end
end
```
This is useful for triggering background jobs or logging events during certain actions.
Remember that Devise uses flash messages to let users know if sign in was successful or failed. Devise expects your application to call `flash[:notice]` and `flash[:alert]` as appropriate. Do not print the entire flash hash, print only specific keys. In some circumstances, Devise adds a `:timedout` key to the flash hash, which is not meant for display. Remove this key from the hash if you intend to print the entire hash.
### Configuring routes
Devise also ships with default routes. If you need to customize them, you should probably be able to do it through the devise_for method. It accepts several options like :class_name, :path_prefix and so on, including the possibility to change path names for I18n:
```ruby
devise_for :users, :path => "auth", :path_names => { :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification', :unlock => 'unblock', :registration => 'register', :sign_up => 'cmon_let_me_in' }
devise_for :users, path: "auth", path_names: { sign_in: 'login', sign_out: 'logout', password: 'secret', confirmation: 'verification', unlock: 'unblock', registration: 'register', sign_up: 'cmon_let_me_in' }
```
Be sure to check `devise_for` documentation for details.
@ -291,11 +317,11 @@ If you have the need for more deep customization, for instance to also allow "/s
```ruby
devise_scope :user do
get "sign_in", :to => "devise/sessions#new"
get "sign_in", to: "devise/sessions#new"
end
```
This way you tell devise to use the scope :user when "/sign_in" is accessed. Notice `devise_scope` is also aliased as `as` in your router.
This way you tell Devise to use the scope `:user` when "/sign_in" is accessed. Notice `devise_scope` is also aliased as `as` in your router.
### I18n
@ -351,7 +377,7 @@ If you're using RSpec, you can put the following inside a file named `spec/suppo
```ruby
RSpec.configure do |config|
config.include Devise::TestHelpers, :type => :controller
config.include Devise::TestHelpers, type: :controller
end
```
@ -381,7 +407,7 @@ There are two things that is important to keep in mind:
Devise comes with Omniauth support out of the box to authenticate with other providers. To use it, just specify your omniauth configuration in `config/initializers/devise.rb`:
```ruby
config.omniauth :github, 'APP_ID', 'APP_SECRET', :scope => 'user,public_repo'
config.omniauth :github, 'APP_ID', 'APP_SECRET', scope: 'user,public_repo'
```
You can read more about Omniauth support in the wiki:
@ -427,7 +453,7 @@ Devise supports ActiveRecord (default) and Mongoid. To choose other ORM, you jus
### Heroku
Using devise on Heroku with Ruby on Rails 3.1 requires setting:
Using Devise on Heroku with Ruby on Rails 3.1 requires setting:
```ruby
config.assets.initialize_on_precompile = false