Skip to content
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.