README.md in clearance-0.12.0 vs README.md in clearance-0.13.0
- old
+ new
@@ -57,47 +57,151 @@
def index
current_user.articles
end
-Customizing
------------
+If you want to know whether the current user is signed in or out, you can use
+these methods in controllers, views, or helpers:
-Clearance is intended to be small, simple, well-tested, and easy to extend.
+ signed_in?
+ signed_out?
-If you ever need to change the logic in any of the four provided controllers,
-subclass the Clearance controller. You don't need to do this by default.
+Typically, you want to have something like this in your app, maybe in a layout:
+ <% if signed_in? %>
+ <%= current_user.email %>
+ <%= link_to "Sign out", sign_out_path, :method => :delete %>
+ <% else %>
+ <%= link_to "Sign in", sign_in_path %>
+ <% end %>
+
+If you ever want to authenticate the user some place other than sessions/new,
+maybe in an API:
+
+ User.authenticate("email@example.com", "password")
+
+Clearance will deliver one email on your app's behalf: when a user resets their password. Therefore, you should change the default email address that email comes from:
+
+ # config/initializers/clearance.rb
+ Clearance.configure do |config|
+ config.mailer_sender = "me@example.com"
+ end
+
+Overriding defaults
+-------------------
+
+Clearance is intended to be small, simple, well-tested, and easy to override defaults.
+
+Overriding routes
+-----------------
+
+See [config/routes.rb](https://github.com/thoughtbot/clearance/blob/master/config/routes.rb) for the default behavior.
+
+To override a Clearance route, redefine it:
+
+ resource :session, :controller => 'sessions'
+
+Overriding controllers
+----------------------
+
+See [app/controllers/clearance](https://github.com/thoughtbot/clearance/tree/master/app/controllers/clearance) for the default behavior.
+
+To override a Clearance controller, subclass it:
+
class SessionsController < Clearance::SessionsController
def new
# my special new action
end
def url_after_create
my_special_path
end
end
-and add your route in config/routes.rb:
+You may want to override entire actions:
- resource :session, :controller => 'sessions'
+ def new
+ end
-See config/routes.rb for all the routes Clearance provides.
+Or, you may want to override private methods that actions use:
-Actions that redirect (create, update, and destroy) in Clearance controllers
-can be overridden by re-defining url_after_(action) methods as seen above.
+ url_after_create
+ url_after_update
+ url_after_destroy
+ flash_failure_after_create
+ flash_failure_after_update
+ flash_failure_when_forbidden
+ forbid_missing_token
+ forbid_non_existent_user
-Clearance is an engine, so it provides views for you. If you want to customize those views, there is a handy shortcut to copy the views into your app:
+Overriding translations
+-----------------------
+All flash messages and email subject lines are stored in [i18n translations](http://guides.rubyonrails.org/i18n.html). Override them like any other translation.
+
+Overriding views
+----------------
+
+See [app/views](https://github.com/thoughtbot/clearance/tree/master/app/views) for the default behavior.
+
+To override those **views**, create them in your own `app/views` directory.
+
+There is a shortcut to copy all Clearance views into your app:
+
rails generate clearance:views
+Overriding the model
+--------------------
+
+If you want to override the **model** behavior, you can include sub-modules of `Clearance::User`:
+
+ extend Clearance::User::ClassMethods
+ include Clearance::User::Validations
+ include Clearance::User::Callbacks
+
+`ClassMethods` contains the `User.authenticate(email, password)` method.
+
+`Validations` contains validations for email and password.
+
+`Callbacks` contains `ActiveRecord` callbacks downcasing the email and generating a remember token.
+
+Overriding the password strategy
+--------------------------------
+
+By default, Clearance uses SHA1 encryption of the user's password. You can provide your own password strategy by creating a module that conforms to an API of two instance methods:
+
+ def authenticated?
+ end
+
+ def encrypt_password
+ end
+
+See [lib/clearance/password_strategies/sha1.rb](https://github.com/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/sha1.rb) for the default behavior.
+
+Once you have an API-compliant module, load it with:
+
+ Clearance.configure do |config|
+ config.password_strategy = MyPasswordStrategy
+ end
+
Optional Cucumber features
--------------------------
-As your app evolves, you want to know that authentication still works. If you
-use [Cucumber](http://cukes.info), run the Clearance features generator:
+Clearance's Cucumber features are dependent on:
+* Cucumber
+* Capybara
+* RSpec
+* Factory Girl
+
+As your app evolves, you want to know that authentication still works. If you've
+installed [Cucumber](http://cukes.info) into your app:
+
+ rails generate cucumber:install
+
+Then, you can use the Clearance features generator:
+
rails generate clearance:features
Edit your Gemfile to include:
gem 'factory_girl_rails'
@@ -142,9 +246,14 @@
get :show
end
it { should respond_with(:success) }
end
+
+Contributing
+------------
+
+Please see CONTRIBUTING.md for details.
Credits
-------
