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
Using this as key in request.env
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 178: def logged_in? 179: user._logged_in? 180: 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 107: def user 108: env = request.env 109: found = env[RAMAZE_HELPER_USER] 110: return found if found 111: 112: model, callback = ancestral_trait.values_at(:user_model, :user_callback) 113: model ||= ::User unless callback 114: env[RAMAZE_HELPER_USER] = Wrapper.new(model, callback) 115: 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[Hash]]
# File lib/ramaze/helper/user.rb, line 153 153: def user_login(creds = request.params) 154: user._login(creds) 155: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.