Permalink
Browse files

Better documentation.

  • Loading branch information...
1 parent a5cb147 commit b21b6291b090cc523ec2b306f9a4a4c9f22a605f @carlosantoniodasilva carlosantoniodasilva committed Oct 17, 2009
View
@@ -97,10 +97,14 @@ There are also some options available for configuring your routes:
map.devise_for :users, :class_name => 'Account'
-* :as => Let's you setup the path name that will be used, as rails routes does. The following route configuration would setup your route as /accounts/session and so on:
+* :as => allows you to setup path name that will be used, as rails routes does. The following route configuration would setup your route as /accounts instead of /users:
map.devise_for :users, :as => 'accounts'
+* :singular => setup the name used to create named routes. By default, for a :users key, it is going to be the singularized version, :user. To configure a named route like account_session_path instead of user_session_path just do:
+
+ map.devise_for :users, :singular => :user
+
* :path_names => configure different path names to overwrite defaults :sign_in, :sign_out, :password and :confirmation.
map.devise_for :users, :path_names => { :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification' }
@@ -1,13 +1,11 @@
class ConfirmationsController < ApplicationController
before_filter :is_devise_resource?
- # GET /confirmation/new
- #
+ # GET /resource/confirmation/new
def new
end
- # POST /confirmation
- #
+ # POST /resource/confirmation
def create
self.resource = resource_class.send_confirmation_instructions(params[resource_name])
@@ -19,8 +17,7 @@ def create
end
end
- # GET /confirmation?perishable_token=abcdef
- #
+ # GET /resource/confirmation?perishable_token=abcdef
def show
self.resource = resource_class.confirm!(:perishable_token => params[:perishable_token])
@@ -1,13 +1,11 @@
class PasswordsController < ApplicationController
before_filter :is_devise_resource?, :require_no_authentication
- # GET /password/new
- #
+ # GET /resource/password/new
def new
end
- # POST /password
- #
+ # POST /resource/password
def create
self.resource = resource_class.send_reset_password_instructions(params[resource_name])
@@ -19,17 +17,16 @@ def create
end
end
- # GET /password/edit?perishable_token=abcdef
- #
+ # GET /resource/password/edit?perishable_token=abcdef
def edit
self.resource = resource_class.new
resource.perishable_token = params[:perishable_token]
end
- # PUT /password
- #
+ # PUT /resource/password
def update
self.resource = resource_class.reset_password!(params[resource_name])
+
if resource.errors.empty?
set_flash_message :success, :updated
redirect_to new_session_path(resource_name)
@@ -2,12 +2,12 @@ class SessionsController < ApplicationController
before_filter :is_devise_resource?
before_filter :require_no_authentication, :only => [ :new, :create ]
- # GET /session/sign_in
+ # GET /resource/sign_in
def new
unauthenticated! if params[:unauthenticated]
end
- # POST /session/sign_in
+ # POST /resource/sign_in
def create
if sign_in(resource_name)
set_flash_message :success, :signed_in
@@ -18,8 +18,7 @@ def create
end
end
- # GET /session/sign_out
- # DELETE /session/sign_out
+ # GET /resource/sign_out
def destroy
set_flash_message :success, :signed_out if signed_in?(resource_name)
sign_out(resource_name)
View
@@ -1,23 +1,22 @@
class Notifier < ::ActionMailer::Base
cattr_accessor :sender
- # Deliver confirmation instructions when the user is created or confirmation
- # is manually requested
- #
+ # Deliver confirmation instructions when the user is created or its email is
+ # updated, and also when confirmation is manually requested
def confirmation_instructions(record)
subject translate(:confirmation_instructions, :default => 'Confirmation instructions')
setup_mail(record)
end
# Deliver reset password instructions when manually requested
- #
def reset_password_instructions(record)
subject translate(:reset_password_instructions, :default => 'Reset password instructions')
setup_mail(record)
end
private
+ # Configure default email options
def setup_mail(record)
from self.class.sender
recipients record.email
View
@@ -12,7 +12,6 @@
# Ensure to include Devise modules only after Rails initialization.
# This way application should have already defined Devise mappings and we are
# able to create default filters.
-#
Rails.configuration.after_initialize do
ActiveRecord::Base.extend Devise::ActiveRecord
end
@@ -1,6 +1,6 @@
module Devise
module ActiveRecord
- # Shortcut method for including all devise modules inside your User class
+ # Shortcut method for including all devise modules inside your model
#
# Examples:
#
@@ -21,7 +21,6 @@ module ActiveRecord
#
# # shortcut to include all modules (same as above)
# devise :all
- #
def devise(*options)
options = [:confirmable, :recoverable, :validatable] if options.include?(:all)
options |= [:authenticable]
@@ -33,6 +32,8 @@ def devise(*options)
end
end
+ # Stores all modules included inside the model, so we are able to verify
+ # which routes are needed.
def devise_modules
@devise_modules ||= []
end
@@ -35,24 +35,28 @@ def sign_out(scope, *args)
warden.logout(scope, *args)
end
- # Define authentication filters based on mappings. These filters should be
- # used inside the controllers as before_filters, so you can control the
- # scope of the user who should be signed in to access that specific
- # controller/action.
- #
+ # Define authentication filters and accessor helpers based on mappings.
+ # These filters should be used inside the controllers as before_filters,
+ # so you can control the scope of the user who should be signed in to
+ # access that specific controller/action.
# Example:
#
# Maps:
- # Devise.map :user, :for => [:authenticable]
- # Devise.map :admin, :for => [:authenticable]
+ # User => :authenticable
+ # Admin => :authenticable
#
# Generated Filters:
# sign_in_user!
# sign_in_admin!
- #
# Use:
# before_filter :sign_in_user! # Tell devise to use :user map
# before_filter :sign_in_admin! # Tell devise to use :admin map
+ #
+ # Generated helpers:
+ # user_signed_in? # Checks whether there is an user signed in or not
+ # admin_signed_in? # Checks whether there is an admin signed in or not
+ # current_user # Current signed in user
+ # current_admin # Currend signed in admin
Devise.mappings.each_key do |mapping|
class_eval <<-METHODS, __FILE__, __LINE__
def sign_in_#{mapping}!
@@ -8,28 +8,48 @@ def self.included(base)
end
end
+ # Gets the actual resource stored in the instance variable
def resource
instance_variable_get(:"@#{resource_name}")
end
+ # Proxy to devise map name
def resource_name
devise_mapping.name
end
+ # Proxy to devise map class
def resource_class
devise_mapping.to
end
protected
+ # Attempt to find the mapped route for devise based on request path
def devise_mapping
@devise_mapping ||= Devise.find_mapping_by_path(request.path)
end
+ # Sets the resource creating an instance variable
def resource=(new_resource)
instance_variable_set(:"@#{resource_name}", new_resource)
end
+ # Sets the flash message with :key, using I18n. By default you are able
+ # to setup your messages using specific resource scope, and if no one is
+ # found we look to default scope.
+ # Example (i18n locale file):
+ #
+ # en:
+ # devise:
+ # passwords:
+ # #default_scope_messages - only if resource_scope is not found
+ # user:
+ # passwords:
+ # #resource_scope_messages
+ #
+ # Please refer to README or en.yml locale file to check what messages are
+ # available.
def set_flash_message(key, kind)
flash[key] = I18n.t(:"#{resource_name}.#{kind}",
:scope => [:devise, controller_name.to_sym], :default => kind)
@@ -2,6 +2,21 @@ module Devise
module Controllers
module UrlHelpers
+ # Create url helpers to be used with resource/scope configuration. Acts as
+ # proxies to the generated routes created by devise.
+ # Resource param can be a string or symbol, a class, or an instance object.
+ # Example using a :user resource:
+ #
+ # new_session_path(:user) => new_user_session_path
+ # session_path(:user) => user_session_path
+ # destroy_session_path(:user) => destroy_user_session_path
+ #
+ # new_password_path(:user) => new_user_password_path
+ # password_path(:user) => user_password_path
+ # edit_password_path(:user) => edit_user_password_path
+ #
+ # new_confirmation_path(:user) => new_user_confirmation_path
+ # confirmation_path(:user) => user_confirmation_path
[:session, :password, :confirmation].each do |module_name|
[:path, :url].each do |path_or_url|
actions = [ nil, :new_ ]
View
@@ -1,10 +1,14 @@
module Devise
+ # Maps controller names to devise modules
CONTROLLERS = {
:sessions => :authenticable,
:passwords => :recoverable,
:confirmations => :confirmable
}.freeze
+ # Responsible for handling devise mappings and routes configuration. Each
+ # resource configured by devise_for in routes is actually creating a mapping
+ # object. Please refer to devise_for in routes for more info.
class Mapping
attr_reader :name, :as, :path_names
@@ -13,9 +17,7 @@ def initialize(name, options)
@klass = (options[:class_name] || name.to_s.classify).to_s
@name = (options[:singular] || name.to_s.singularize).to_sym
@path_names = options[:path_names] || {}
- [:sign_in, :sign_out, :password, :confirmation].each do |path_name|
- @path_names[path_name] ||= path_name.to_s
- end
+
end
# Return modules for the mapping.
@@ -36,18 +38,37 @@ def allows?(controller)
self.for.include?(CONTROLLERS[controller.to_sym])
end
+ # Create magic predicates for verifying what module is activated by this map.
+ # Example:
+ #
+ # def confirmable?
+ # self.for.include?(:confirmable)
+ # end
CONTROLLERS.values.each do |m|
class_eval <<-METHOD, __FILE__, __LINE__
def #{m}?
self.for.include?(:#{m})
end
METHOD
end
+
+ private
+
+ # Configure default path names, allowing the user overwrite defaults by
+ # passing a hash in :path_names.
+ def setup_path_names
+ [:sign_in, :sign_out, :password, :confirmation].each do |path_name|
+ @path_names[path_name] ||= path_name.to_s
+ end
+ end
end
mattr_accessor :mappings
self.mappings = {}
+ # Loop through all mappings looking for a map that matches with the requested
+ # path (ie /users/sign_in). The important part here is the key :users. If no
+ # map is found just returns nil.
def self.find_mapping_by_path(path)
route = path.split("/")[1]
return nil unless route
@@ -17,7 +17,6 @@ module Models
#
# User.authenticate('email@test.com', 'password123') # returns authenticated user or nil
# User.find(1).valid_password?('password123') # returns true/false
- #
module Authenticable
mattr_accessor :pepper, :stretches
@@ -44,7 +43,6 @@ def password=(new_password)
end
# Verifies whether an incoming_password (ie from login) is the user password
- #
def valid_password?(incoming_password)
password_digest(incoming_password) == encrypted_password
end
@@ -53,7 +51,6 @@ def valid_password?(incoming_password)
# Gererates a default password digest based on salt, pepper and the
# incoming password
- #
def password_digest(password_to_digest)
digest = pepper
stretches.times { digest = secure_digest(password_salt, digest, password_to_digest, pepper) }
@@ -63,13 +60,11 @@ def password_digest(password_to_digest)
# Generate a SHA1 digest joining args. Generated token is something like
#
# --arg1--arg2--arg3--argN--
- #
def secure_digest(*tokens)
::Digest::SHA1.hexdigest('--' << tokens.flatten.join('--') << '--')
end
# Generate a friendly string randomically to be used as token
- #
def friendly_token
ActiveSupport::SecureRandom.base64(15).tr('+/=', '-_ ').strip.delete("\n")
end
@@ -79,7 +74,6 @@ module ClassMethods
# Authenticate a user based on email and password. Returns the
# authenticated user if it's valid or nil.
# Attributes are :email and :password
- #
def authenticate(attributes={})
authenticable = self.find_by_email(attributes[:email])
authenticable if authenticable.try(:valid_password?, attributes[:password])
Oops, something went wrong.

0 comments on commit b21b629

Please sign in to comment.