Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

improving the README's documentation. all overrides should now be doc…

…umented clearly, with links to the engine's codebase for further exploration.
  • Loading branch information...
1 parent e01f366 commit 26933c5cfbc3b7f447e35906e937d3cda566e4bd @croaky croaky committed
@@ -79,13 +79,33 @@ maybe in an API:
User.authenticate("", "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 = ""
+ end
Overriding defaults
Clearance is intended to be small, simple, well-tested, and easy to override defaults.
-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.
+Overriding routes
+See [config/routes.rb]( for the default behavior.
+To override a Clearance route, redefine it:
+ resource :session, :controller => 'sessions'
+Overriding controllers
+See [app/controllers/clearance]( for the default behavior.
+To override a Clearance controller, subclass it:
class SessionsController < Clearance::SessionsController
def new
@@ -97,19 +117,72 @@ subclass the Clearance controller. You don't need to do this by default.
-and add your route in config/routes.rb:
+You may want to override entire actions:
- resource :session, :controller => 'sessions'
+ def new
+ end
+Or, you may want to override private methods that actions use:
+ 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
+Overriding translations
+All flash messages and email subject lines are stored in [i18n translations]( Override them like any other translation.
-See config/routes.rb for all the routes Clearance provides.
+Overriding views
-Actions that redirect (create, update, and destroy) in Clearance controllers
-can be overridden by re-defining url\_after\_(action) methods as seen above.
+See [app/views]( for the default behavior.
-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:
+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]( 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
1  lib/clearance/configuration.rb
@@ -24,6 +24,7 @@ class << self
# Clearance.configure do |config|
# config.mailer_sender = ''
# config.cookie_expiration = lambda { 2.weeks.from_now.utc }
+ # config.password_strategy = MyPasswordStrategy
# end
def self.configure
self.configuration ||=
2  lib/clearance/user.rb
@@ -10,7 +10,7 @@ module User
# extend and include à la carte.
# @example
- # include Callbacks
+ # include Clearance::User::Callbacks
# @see Validations
# @see Callbacks

0 comments on commit 26933c5

Please sign in to comment.
Something went wrong with that request. Please try again.