Skip to content
Newer
Older
100644 389 lines (247 sloc) 15.1 KB
a71a352 @josevalim Release 2.0.0
josevalim authored Jan 26, 2012
1 *IMPORTANT:* Devise 2.0.0 is out. If you are upgrading, please read: https://github.com/plataformatec/devise/wiki/How-To:-Upgrade-to-Devise-2.0
b71028d @josevalim Add a note to the README.
josevalim authored Dec 19, 2011
2
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
3 ## Devise
673fda9 @josevalim First commit.
josevalim authored Sep 16, 2009
4
222e606 Added a documentup link on README
Rodrigo Flores authored Feb 3, 2012
5 INFO: This README is [also available in a friendly navigable format](http://devise.plataformatec.com.br/).
6
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
7 [![Build Status](https://secure.travis-ci.org/plataformatec/devise.png)](http://travis-ci.org/plataformatec/devise)
538c16c Added CI status to the README
Rodrigo Flores authored Nov 6, 2011
8
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
9 Devise is a flexible authentication solution for Rails based on Warden. It:
10
11 * Is Rack based;
12 * Is a complete MVC solution based on Rails engines;
13 * Allows you to have multiple roles (or models/scopes) signed in at the same time;
14 * Is based on a modularity concept: use just what you really need.
15
a729e05 @rumblestrut Changed "It's composed of 12 modules:" to "It's comprised of 12 modul…
rumblestrut authored Aug 10, 2011
16 It's comprised of 12 modules:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
17
f06bed2 corrected 'an user' to 'a user' in comments and docs
Nico Ritsche authored Feb 6, 2011
18 * Database Authenticatable: encrypts and stores a password in the database to validate the authenticity of a user while signing in. The authentication can be done both through POST requests or HTTP Basic Authentication.
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 22, 2010
19 * Token Authenticatable: signs in a user based on an authentication token (also known as "single access token"). The token can be given both through query string or HTTP Basic Authentication.
3d1152f @josevalim Update README and CHANGELOG.
josevalim authored Oct 15, 2010
20 * Omniauthable: adds Omniauth (github.com/intridea/omniauth) support;
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
21 * Confirmable: sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.
22 * Recoverable: resets the user password and sends reset instructions.
08c5179 @josevalim Update registerable on readme.
josevalim authored May 11, 2010
23 * Registerable: handles signing up users through a registration process, also allowing them to edit and destroy their account.
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
24 * Rememberable: manages generating and clearing a token for remembering the user from a saved cookie.
25 * Trackable: tracks sign in count, timestamps and IP address.
26 * Timeoutable: expires sessions that have no activity in a specified period of time.
27 * Validatable: provides validations of email and password. It's optional and can be customized, so you're able to define your own validations.
28 * Lockable: locks an account after a specified number of failed sign-in attempts. Can unlock via email or after a specified time period.
2305e8f @josevalim Improve README.
josevalim authored Nov 30, 2010
29 * Encryptable: adds support of other authentication mechanisms besides the built-in Bcrypt (the default).
673fda9 @josevalim First commit.
josevalim authored Sep 16, 2009
30
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
31 ## Information
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
32
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
33 ### The Devise wiki
2fe1a69 @josevalim Added jeweler to rakefile and version.
josevalim authored Oct 21, 2009
34
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
35 The Devise Wiki has lots of additional information about Devise including many "how-to" articles and answers to the most frequently asked questions. Please browse the Wiki after finishing this README:
84c34ff @josevalim Be more specific about master.
josevalim authored Jun 28, 2010
36
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
37 https://wiki.github.com/plataformatec/devise
6f450d7 @carlosantoniodasilva Fix requiring devise mapping, and adding some documentation about rou…
carlosantoniodasilva authored Oct 21, 2009
38
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
39 ### Bug reports
3432c9e @josevalim Simplify autoload stack.
josevalim authored Dec 12, 2009
40
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
41 If you discover a problem with Devise, we would like to know about it. However, we ask that you please review these guidelines before submitting a bug report:
7c82d3e @josevalim Move the generator bit to the top.
josevalim authored May 21, 2010
42
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
43 https://github.com/plataformatec/devise/wiki/Bug-reports
7c82d3e @josevalim Move the generator bit to the top.
josevalim authored May 21, 2010
44
971f68f @joliss README: Call the Google Group a mailing list; merge Testing section i…
joliss authored Jan 15, 2011
45 If you found a security bug, do *NOT* use the GitHub issue tracker. Send email or a private GitHub message to the maintainers listed at the bottom of the README.
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
46
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
47 ### Mailing list
0bd7546 @josevalim Update README.
josevalim authored Apr 5, 2010
48
971f68f @joliss README: Call the Google Group a mailing list; merge Testing section i…
joliss authored Jan 15, 2011
49 If you have any questions, comments, or concerns, please use the Google Group instead of the GitHub issue tracker:
6d6633d @josevalim Release 1.1.pre which is Rails 3 compatible.
josevalim authored Feb 17, 2010
50
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
51 https://groups.google.com/group/plataformatec-devise
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
52
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
53 ### RDocs
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
54
55 You can view the Devise documentation in RDoc format here:
56
57 http://rubydoc.info/github/plataformatec/devise/master/frames
6d6633d @josevalim Release 1.1.pre which is Rails 3 compatible.
josevalim authored Feb 17, 2010
58
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
59 If you need to use Devise with Rails 2.3, you can always run "gem server" from the command line after you install the gem to access the old documentation.
6d6633d @josevalim Release 1.1.pre which is Rails 3 compatible.
josevalim authored Feb 17, 2010
60
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
61 ### Example applications
6d6633d @josevalim Release 1.1.pre which is Rails 3 compatible.
josevalim authored Feb 17, 2010
62
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
63 There are a few example applications available on GitHub that demonstrate various features of Devise with different versions of Rails. You can view them here:
6d6633d @josevalim Release 1.1.pre which is Rails 3 compatible.
josevalim authored Feb 17, 2010
64
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
65 https://github.com/plataformatec/devise/wiki/Example-Applications
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
66
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
67 ### Extensions
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
68
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
69 Our community has created a number of extensions that add functionality above and beyond what is included with Devise. You can view a list of available extensions and add your own here:
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
70
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
71 https://github.com/plataformatec/devise/wiki/Extensions
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
72
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
73 ### Contributing
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
74
75 We hope that you will consider contributing to Devise. Please read this short overview for some information about how to get started:
76
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
77 https://github.com/plataformatec/devise/wiki/Contributing
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
78
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
79 You will usually want to write tests for your changes. To run the test suite, go into Devise's top-level directory and run "bundle install" and "rake". For the tests to pass, you will need to have a MongoDB server (version 2.0 or newer) running on your system.
f96061b @josevalim Update docs and CHANGELOG based on the 1.1.3 release from v1.1 branch.
josevalim authored Sep 24, 2010
80
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
81 ## Starting with Rails?
5f93d83 @josevalim A tip for newcommers.
josevalim authored Jan 31, 2011
82
76a4800 @josevalim Words.
josevalim authored Jan 31, 2011
83 If you are building your first Rails application, we recommend you to *not* use Devise. Devise requires a good understanding of the Rails Framework. In such cases, we advise you to start a simple authentication system from scratch, today we have two resources:
5f93d83 @josevalim A tip for newcommers.
josevalim authored Jan 31, 2011
84
85 * Michael Hartl's online book: http://railstutorial.org/chapters/modeling-and-viewing-users-two#top
86 * Ryan Bates' Railscast: http://railscasts.com/episodes/250-authentication-from-scratch
87
762f390 @waynn quick typo fix
waynn authored Jul 11, 2011
88 Once you have solidified your understanding of Rails and authentication mechanisms, we assure you Devise will be very pleasant to work with. :)
5f93d83 @josevalim A tip for newcommers.
josevalim authored Jan 31, 2011
89
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
90 ## Getting started
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
91
dfcf825 @ysiadf Update README.doc to specify adding devise to the Gemfile.
ysiadf authored Jan 27, 2012
92 Devise 2.0 works with Rails 3.1 onwards. You can add it to your Gemfile with:
cb285bf @carlosantoniodasilva Updating readme with missing migration info.
carlosantoniodasilva authored Oct 15, 2009
93
dfcf825 @ysiadf Update README.doc to specify adding devise to the Gemfile.
ysiadf authored Jan 27, 2012
94 gem 'devise'
95
96 Run the bundle command to install it.
d26f90f @carlosantoniodasilva Updating docs and TODO.
carlosantoniodasilva authored Oct 20, 2009
97
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
98 After you install Devise and add it to your Gemfile, you need to run the generator:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
99
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
100 ```console
101 rails generate devise:install
102 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
103
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
104 The generator will install an initializer which describes ALL Devise's configuration options and you MUST take a look at it. When you are done, you are ready to add Devise to any of your models using the generator:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
105
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
106 ```console
107 rails generate devise MODEL
108 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
109
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
110 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 Devise controller.
efc0ae2 @josevalim Deprecate :all.
josevalim authored Jan 13, 2010
111
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
112 ### Controller filters and helpers
3209e7d @josevalim Renamed confirm_in to confirm_within.
josevalim authored Oct 30, 2009
113
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
114 Devise will create some helpers to use inside your controllers and views. To set up a controller with user authentication, just add this before_filter:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
115
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
116 ```ruby
117 before_filter :authenticate_user!
118 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
119
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
120 To verify if a user is signed in, use the following helper:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
121
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
122 ```ruby
123 user_signed_in?
124 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
125
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
126 For the current signed-in user, this helper is available:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
127
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
128 ```ruby
129 current_user
130 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
131
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
132 You can access the session for this scope:
cce3f58 @carlosantoniodasilva Fix typo and filter info in readme.
carlosantoniodasilva authored Oct 18, 2009
133
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
134 ```ruby
135 user_session
136 ```
cce3f58 @carlosantoniodasilva Fix typo and filter info in readme.
carlosantoniodasilva authored Oct 18, 2009
137
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
138 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:
6f450d7 @carlosantoniodasilva Fix requiring devise mapping, and adding some documentation about rou…
carlosantoniodasilva authored Oct 21, 2009
139
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
140 ```ruby
141 root :to => "home#index"
142 ```
6f450d7 @carlosantoniodasilva Fix requiring devise mapping, and adding some documentation about rou…
carlosantoniodasilva authored Oct 21, 2009
143
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
144 You can also overwrite +after_sign_in_path_for+ and +after_sign_out_path_for+ to customize your redirect hooks.
d445b4b @josevalim Create after_sign_in_path_for and after_sign_out_path_for hooks and s…
josevalim authored Nov 19, 2009
145
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
146 Finally, you need to set up default url options for the mailer in each environment. Here is the configuration for "config/environments/development.rb":
6f450d7 @carlosantoniodasilva Fix requiring devise mapping, and adding some documentation about rou…
carlosantoniodasilva authored Oct 21, 2009
147
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
148 ```ruby
149 config.action_mailer.default_url_options = { :host => 'localhost:3000' }
150 ```
fc08a7c @carlosantoniodasilva Changing resource_home_path to resource_root_path and add the same re…
carlosantoniodasilva authored Oct 19, 2009
151
67645c6 @josevalim Move extra helpers names to the bottom.
josevalim authored Nov 15, 2010
152 Notice that if your devise model is not called "user" but "member", then the helpers you should use are:
153
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
154 ```ruby
155 before_filter :authenticate_member!
67645c6 @josevalim Move extra helpers names to the bottom.
josevalim authored Nov 15, 2010
156
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
157 member_signed_in?
67645c6 @josevalim Move extra helpers names to the bottom.
josevalim authored Nov 15, 2010
158
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
159 current_member
67645c6 @josevalim Move extra helpers names to the bottom.
josevalim authored Nov 15, 2010
160
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
161 member_session
162 ```
67645c6 @josevalim Move extra helpers names to the bottom.
josevalim authored Nov 15, 2010
163
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
164 ### Configuring Models
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
165
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
166 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:
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
167
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
168 ```ruby
169 devise :database_authenticatable, :registerable, :confirmable, :recoverable, :stretches => 20
170 ```
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
171
0908870 @josevalim Extract encryptors into their own module for better bcrypt support.
josevalim authored Sep 25, 2010
172 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.
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
173
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
174 ### Configuring multiple models
3209e7d @josevalim Renamed confirm_in to confirm_within.
josevalim authored Oct 30, 2009
175
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
176 Devise allows you to set up as many roles as you want. For example, you may have a User model and also want an Admin model with just authentication and timeoutable features. If so, just follow these steps:
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
177
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
178 ```ruby
179 # Create a migration with the required fields
180 create_table :admins do |t|
181 t.string :email
182 t.string :encrypted_password
183 t.timestamps
184 end
9feb945 @josevalim Allow page after sign in to be configured.
josevalim authored Oct 18, 2009
185
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
186 # Inside your Admin model
187 devise :database_authenticatable, :timeoutable
9feb945 @josevalim Allow page after sign in to be configured.
josevalim authored Oct 18, 2009
188
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
189 # Inside your routes
190 devise_for :admins
9feb945 @josevalim Allow page after sign in to be configured.
josevalim authored Oct 18, 2009
191
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
192 # Inside your protected controller
193 before_filter :authenticate_admin!
9feb945 @josevalim Allow page after sign in to be configured.
josevalim authored Oct 18, 2009
194
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
195 # Inside your controllers and views
196 admin_signed_in?
197 current_admin
198 admin_session
199 ```
493f91f @carlosantoniodasilva Readme updates.
carlosantoniodasilva authored Oct 13, 2009
200
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
201 On the other hand, you can simply run the generator!
202
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
203 ### Configuring views
efc0ae2 @josevalim Deprecate :all.
josevalim authored Jan 13, 2010
204
bf63824 @josevalim Improve wording in the README.
josevalim authored Apr 12, 2010
205 We built Devise to help you quickly develop an application that uses authentication. However, we don't want to be in your way when you need to customize it.
0a317c9 @carlosantoniodasilva README with some Generators info.
carlosantoniodasilva authored Oct 23, 2009
206
13bd4ce @pcantrell Grammar fix.
pcantrell authored Jan 11, 2012
207 Since Devise is an engine, all its views are packaged inside the gem. These views will help you get started, but after some time you may want to change them. If this is the case, you just need to invoke the following generator, and it will copy all views to your application:
0a317c9 @carlosantoniodasilva README with some Generators info.
carlosantoniodasilva authored Oct 23, 2009
208
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
209 ```console
210 rails generate devise:views
211 ```
efc0ae2 @josevalim Deprecate :all.
josevalim authored Jan 13, 2010
212
eb3118e @josevalim Add OAuth2 documentation.
josevalim authored Jul 15, 2010
213 If you have more than one role in your application (such as "User" and "Admin"), you will notice that Devise uses the same views for all roles. 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".
214
215 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:
216
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
217 ```console
218 rails generate devise:views users
219 ```
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
220
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
221 ### Configuring controllers
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
222
bf63824 @josevalim Improve wording in the README.
josevalim authored Apr 12, 2010
223 If the customization at the views level is not enough, you can customize each controller by following these steps:
224
225 1) Create your custom controller, for example a Admins::SessionsController:
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
226
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
227 ```ruby
228 class Admins::SessionsController < Devise::SessionsController
229 end
230 ```
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
231
bf63824 @josevalim Improve wording in the README.
josevalim authored Apr 12, 2010
232 2) Tell the router to use this controller:
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
233
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
234 ```ruby
235 devise_for :admins, :controllers => { :sessions => "admins/sessions" }
236 ```
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
237
bf63824 @josevalim Improve wording in the README.
josevalim authored Apr 12, 2010
238 3) And since we changed the controller, it won't use the "devise/sessions" views, so remember to copy "devise/sessions" to "admin/sessions".
f6cc219 @josevalim Devise now allows you to have custom controlleers. Check the README f…
josevalim authored Feb 17, 2010
239
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
240 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.
6d29bcc @paulca Add mention of flash[:notice] and flash[:alert]
paulca authored Feb 15, 2010
241
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
242 ### Configuring routes
a36cb6e @josevalim Improve docs for routes customization.
josevalim authored Jul 19, 2010
243
244 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:
245
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
246 ```ruby
247 devise_for :users, :path => "usuarios", :path_names => { :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification', :unlock => 'unblock', :registration => 'register', :sign_up => 'cmon_let_me_in' }
248 ```
a36cb6e @josevalim Improve docs for routes customization.
josevalim authored Jul 18, 2010
249
b061f98 @josevalim Update README to remove reference to old migration helpers.
josevalim authored Jan 27, 2012
250 Be sure to check +devise_for+ documentation for details.
a36cb6e @josevalim Improve docs for routes customization.
josevalim authored Jul 18, 2010
251
252 If you have the need for more deep customization, for instance to also allow "/sign_in" besides "/users/sign_in", all you need to do is to create your routes normally and wrap them in a +devise_scope+ block in the router:
253
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
254 ```ruby
255 devise_scope :user do
256 get "sign_in", :to => "devise/sessions#new"
257 end
258 ```
c0c7aef @josevalim Smallish update to README.
josevalim authored Aug 2, 2010
259
260 This way you tell devise to use the scope :user when "/sign_in" is accessed. Notice +devise_scope+ is also aliased as +as+ and you can also give a block to +devise_for+, resulting in the same behavior:
261
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
262 ```ruby
263 devise_for :users do
264 get "sign_in", :to => "devise/sessions#new"
265 end
266 ```
a36cb6e @josevalim Improve docs for routes customization.
josevalim authored Jul 18, 2010
267
c0c7aef @josevalim Smallish update to README.
josevalim authored Aug 2, 2010
268 Feel free to choose the one you prefer!
a36cb6e @josevalim Improve docs for routes customization.
josevalim authored Jul 18, 2010
269
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
270 ### I18n
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
271
c3d9209 @Juanmcuello Update README.
Juanmcuello authored Apr 17, 2011
272 Devise uses flash messages with I18n with the flash keys :notice and :alert. To customize your app, you can set up your locale file:
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
273
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
274 ```yaml
275 en:
276 devise:
277 sessions:
278 signed_in: 'Signed in successfully.'
279 ```
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
280
475da06 @josevalim Make ActionMailer and ActionController more consistent by always usin…
josevalim authored Oct 29, 2009
281 You can also create distinct messages based on the resource you've configured using the singular name given in routes:
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
282
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
283 ```yaml
284 en:
285 devise:
286 sessions:
287 user:
288 signed_in: 'Welcome user, you are signed in.'
289 admin:
290 signed_in: 'Hello admin!'
291 ```
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
292
eb3118e @josevalim Add OAuth2 documentation.
josevalim authored Jul 15, 2010
293 The Devise mailer uses a similar pattern to create subject messages:
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
294
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
295 ```yaml
296 en:
297 devise:
298 mailer:
299 confirmation_instructions:
300 subject: 'Hello everybody!'
301 user_subject: 'Hello User! Please confirm your email'
302 reset_password_instructions:
303 subject: 'Reset instructions'
304 ```
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
305
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
306 Take a look at our locale file to check all available messages. You may also be interested in one of the many translations that are available on our wiki:
0eb8b3b @carlosantoniodasilva Mailer subjects namespaced by model
carlosantoniodasilva authored Oct 20, 2009
307
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
308 https://github.com/plataformatec/devise/wiki/I18n
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
309
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
310 ### Test helpers
97a7f0e @josevalim Added test helpers.
josevalim authored Nov 16, 2009
311
d9fbdff @josevalim More testing info in README.
josevalim authored Dec 7, 2009
312 Devise includes some tests helpers for functional specs. To use them, you just need to include Devise::TestHelpers in your test class and use the sign_in and sign_out method. Such methods have the same signature as in controllers:
97a7f0e @josevalim Added test helpers.
josevalim authored Nov 16, 2009
313
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
314 ```ruby
315 sign_in :user, @user # sign_in(scope, resource)
316 sign_in @user # sign_in(resource)
97a7f0e @josevalim Added test helpers.
josevalim authored Nov 16, 2009
317
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
318 sign_out :user # sign_out(scope)
319 sign_out @user # sign_out(resource)
320 ```
97a7f0e @josevalim Added test helpers.
josevalim authored Nov 16, 2009
321
2d67432 @pat Expanding on testing docs a little to be more useful for those using …
pat authored Jul 27, 2010
322 You can include the Devise Test Helpers in all of your tests by adding the following to the bottom of your test/test_helper.rb file:
529cd8b @trevorturk Add example for including Devise::TestHelpers in all functional tests…
trevorturk authored Nov 20, 2009
323
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
324 ```ruby
325 class ActionController::TestCase
326 include Devise::TestHelpers
327 end
328 ```
529cd8b @trevorturk Add example for including Devise::TestHelpers in all functional tests…
trevorturk authored Nov 20, 2009
329
fd35b36 @pat Presumed Markdown syntax - switching inline code to RDoc.
pat authored Jul 27, 2010
330 If you're using RSpec and want the helpers automatically included within all +describe+ blocks, add a file called spec/support/devise.rb with the following contents:
2d67432 @pat Expanding on testing docs a little to be more useful for those using …
pat authored Jul 27, 2010
331
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
332 ```ruby
333 RSpec.configure do |config|
334 config.include Devise::TestHelpers, :type => :controller
335 end
336 ```
2d67432 @pat Expanding on testing docs a little to be more useful for those using …
pat authored Jul 27, 2010
337
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
338 Do not use such helpers for integration tests such as Cucumber or Webrat. Instead, fill in the form or explicitly set the user in session. For more tips, check the wiki (https://wiki.github.com/plataformatec/devise).
d9fbdff @josevalim More testing info in README.
josevalim authored Dec 7, 2009
339
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
340 ### Omniauth
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
341
1f51524 @josevalim Edited README.rdoc via GitHub
josevalim authored Apr 11, 2011
342 Devise comes with Omniauth support out of the box to authenticate from other providers. You can read more about Omniauth support in the wiki:
9d6a78f @josevalim Add ldap_authenticatable to README.
josevalim authored Apr 22, 2010
343
1f51524 @josevalim Edited README.rdoc via GitHub
josevalim authored Apr 11, 2011
344 * https://github.com/plataformatec/devise/wiki/OmniAuth:-Overview
6754ae7 @josevalim Update README.
josevalim authored Aug 17, 2010
345
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
346 ### Other ORMs
f96061b @josevalim Update docs and CHANGELOG based on the 1.1.3 release from v1.1 branch.
josevalim authored Sep 24, 2010
347
348 Devise supports ActiveRecord (default) and Mongoid. To choose other ORM, you just need to require it in the initializer file.
349
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
350 ### Migrating from other solutions
1db86a0 @josevalim More information about ecosystem in the README.
josevalim authored Apr 15, 2010
351
0908870 @josevalim Extract encryptors into their own module for better bcrypt support.
josevalim authored Sep 25, 2010
352 Devise implements encryption strategies for Clearance, Authlogic and Restful-Authentication. To make use of these strategies, you need set the desired encryptor in the encryptor initializer config option and add :encryptable to your model. You might also need to rename your encrypted password and salt columns to match Devise's fields (encrypted_password and password_salt).
238226e @carlosantoniodasilva Adding a small note about security and issues
carlosantoniodasilva authored Jul 5, 2010
353
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
354 ## Troubleshooting
52282a5 @avocade Update README with troubleshooting for heroku
avocade authored Oct 10, 2011
355
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
356 ### Heroku
52282a5 @avocade Update README with troubleshooting for heroku
avocade authored Oct 10, 2011
357
358 Using devise on Heroku with Ruby on Rails 3.1 requires setting:
359
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
360 ```ruby
361 config.assets.initialize_on_precompile = false
362 ```
52282a5 @avocade Update README with troubleshooting for heroku
avocade authored Oct 10, 2011
363
364 Read more about the potential issues at http://guides.rubyonrails.org/asset_pipeline.html
365
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
366 ## Additional information
238226e @carlosantoniodasilva Adding a small note about security and issues
carlosantoniodasilva authored Jul 5, 2010
367
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
368 ### Warden
6d09eb6 @josevalim Tidying up encryptors.
josevalim authored Nov 10, 2009
369
fdb4cd5 @trevorturk Major update to README - encourage use of the Wiki
trevorturk authored Sep 21, 2010
370 Devise is based on Warden, which is a general Rack authentication framework created by Daniel Neighman. We encourage you to read more about Warden here:
eb3118e @josevalim Add OAuth2 documentation.
josevalim authored Jul 15, 2010
371
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
372 https://github.com/hassox/warden
6bd8846 @josevalim Update Maintainers and Contributors section. Add Grimen for his work …
josevalim authored Dec 23, 2009
373
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
374 ### Contributors
6bd8846 @josevalim Update Maintainers and Contributors section. Add Grimen for his work …
josevalim authored Dec 23, 2009
375
9bdc711 @josevalim Update README.
josevalim authored May 3, 2010
376 We have a long list of valued contributors. Check them all at:
377
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
378 https://github.com/plataformatec/devise/contributors
6d09eb6 @josevalim Tidying up encryptors.
josevalim authored Nov 10, 2009
379
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
380 ### Maintainers
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
381
13ed218 many typos (http -> https)
Andrey Korobkov authored Oct 13, 2011
382 * José Valim (https://github.com/josevalim)
383 * Carlos Antônio da Silva (https://github.com/carlosantoniodasilva)
b79c691 Adding myself to the team! w00t!
Rodrigo Flores authored Nov 30, 2011
384 * Rodrigo Flores (https://github.com/rodrigoflores)
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
385
bb6d89b @carlosantoniodasilva Change README do markdown
carlosantoniodasilva authored Jan 30, 2012
386 ## License
5c59f4c @fortuity Fixes to syntax, diction and spelling in README.
fortuity authored Feb 27, 2010
387
95399f1 @carlosantoniodasilva 2012 [ci skip]
carlosantoniodasilva authored Jan 24, 2012
388 MIT License. Copyright 2012 Plataforma Tecnologia. http://blog.plataformatec.com.br
Something went wrong with that request. Please try again.