module Ramaze::Helper::UserHelper
This helper provides a convenience wrapper for handling authentication and persistence of users.
On every request, when you use the {UserHelper#user} method for the first time, we confirm the authentication and store the returned object in the request.env, usually this will involve a request to your database.
@example Basic usage with User::authenticate
# We assume that User::[] will make a query and returns the requested # User instance. This instance will be wrapped and cached. class User def self.authenticate(creds) User[:name => creds['name'], :pass => creds['pass']] end end class Profiles < Ramaze::Controller helper :user def edit redirect_referrer unless logged_in? "Your profile is shown, your are logged in." end end class Accounts < Ramaze::Controller helper :user def login return unless request.post? user_login(request.subset(:name, :pass)) redirect Profiles.r(:edit) end def logout user_logout redirect_referer end end
On every request it checks authentication again and retrieves the model, we are not using a normal cache for this as it may lead to behaviour that is very hard to predict and debug.
You can however, add your own caching quite easily.
@example caching the authentication lookup with memcached
# Add the name of the cache you are going to use for the authentication # and set all caches to use memcached Ramaze::Cache.options do |cache| cache.names = [:session, :user] cache.default = Ramaze::Cache::MemCache end class User # Try to fetch the user from the cache, if that fails make a query. # We are using a ttl (time to live) of one hour, that's just to show # you how to do it and not necessary. def self.authenticate(credentials) cache = Ramaze::Cache.user if user = cache[credentials] return user elsif user = User[:name => creds['name'], :pass => creds['pass']] cache.store(credentials, user, :ttl => 3600) end end end
@example Using a lambda instead of User::authenticate
# assumes all your controllers inherit from this one class Controller < Ramaze::Controller trait :user_callback => lambda{|creds| User[:name => creds['name'], :pass => creds['pass']] } end
@example Using a different model instead of User
# assumes all your controllers inherit from this one class Controller < Ramaze::Controller trait :user_model => Account end
@author manveru
Constants
- RAMAZE_HELPER_USER
Using this as key in request.env
Public Instance Methods
Checks if the user is logged in and returns true if this is the case and false otherwise.
@author manveru @api external @see Ramaze::Helper::User::Wrapper#_logged_in? @return [TrueClass|FalseClass] whether the user is logged in already.
# File lib/ramaze/helper/user.rb, line 178 def logged_in? user._logged_in? end
Use this method in your application, but do not use it in conditionals as it will never be nil or false.
@api external @author manveru @return [Ramaze::Helper::User::Wrapper] wrapped return value from
model or callback
# File lib/ramaze/helper/user.rb, line 107 def user env = request.env found = env[RAMAZE_HELPER_USER] return found if found model, callback = ancestral_trait.values_at(:user_model, :user_callback) model ||= ::User unless callback env[RAMAZE_HELPER_USER] = Wrapper.new(model, callback) end
This method is used to authenticate a user against the supplied credentials (which default to “request.params“).
This method is a proxy to user._login which returns the value as returned by “Ramaze::Helper::User::Wrapper#_login“.
The supplied argument should be a hash with the user's credentials. The credentials hash may use any naming for the hash keys as long as they are consistent with the model which authenticates them (through the “authenticate()“ method) such as:
{"username" =>"name", "password" => "the_passwd"}
On success it returns a hash of the credentials embedded within a hash whose only key is ':credentials' such as the following:
{:credentials=>{"username"=>"myuser", "password"=>"mypassword"}}
On failure to authenticate this method returns nil.
@example
auth = {"username" => "my_username", "password" => "mypass"} creds = user_login(auth) if creds respond 'You have been logged in as #{creds[:credentials]["username"]}', 200 else respond 'You could not be logged in', 401 end
@author manveru @api external @see Ramaze::Helper::User::Wrapper#_login @param [Hash] creds the credentials that will be passed to the callback or model. @return [nil Hash]
# File lib/ramaze/helper/user.rb, line 153 def user_login(creds = request.params) user._login(creds) end
Shortcut for user._logout
@author manveru @api external @see Ramaze::Helper::User::Wrapper#_logout @return [NilClass]
# File lib/ramaze/helper/user.rb, line 165 def user_logout user._logout end