Module | Ramaze::Helper::User
In: | lib/ramaze/helper/user.rb

This helper provides a convenience wrapper for handling authentication and persistence of users.

On every request, when you use the {User#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 inhert 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 inhert from this one

      class Controller < Ramaze::Controller
        trait :user_model => Account
      end

@author manveru @todo convert the examples into real examples with specs

### Methods

logged_in? user user_login user_logout

### Classes and Modules

Class Ramaze::Helper::User::Wrapper

### Constants

RAMAZE_HELPER_USER | = | 'ramaze.helper.user'.freeze |  | Using this as key in request.env

### Public Instance methods

logged_in?()

@return [true false] whether the user is logged in already.

@api external @see Ramaze::Helper::User::Wrapper#_logged_in? @author manveru

user()

Use this method in your application, but do not use it in conditionals as it will never be nil or false.

@return [Ramaze::Helper::User::Wrapper] wrapped return value from model or callback

@api external @author manveru

user_login(creds = request.params)

shortcut for user._login but default argument are request.params

@param [Hash] creds the credentials that will be passed to callback or model

@return [nil Hash] the given creds are returned on successful login

@api external @see Ramaze::Helper::User::Wrapper#_login @author manveru

user_logout()

shortcut for user._logout

@return [nil]

@api external @see Ramaze::Helper::User::Wrapper#_logout @author manveru

[Validate]