ramaze 0.3.9.1 → 2023.01.06

data/lib/ramaze/helper/user.rb

@@ -1,63 +1,284 @@
 module Ramaze
   module Helper
-    module User
-      def self.inherited(klass)
-        klass.trait :user_model => ::User
-      end
+    ##
+    # 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
+    #
+    module UserHelper
+      # Using this as key in request.env
+      RAMAZE_HELPER_USER = 'ramaze.helper.user'.freeze
 
+      ##
+      # 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
+      #
       def user
-        if instance_variable_defined?('@user_helper')
-          @user_helper
-        else
-          @user_helper = Wrapper.new ancestral_trait[:user_model]
-        end
+        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[Hash]]
+      #
+      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]
+      #
+      def user_logout
+        user._logout
       end
 
-      class Wrapper
-        thread_accessor :session
-        attr_accessor :user
+      ##
+      # 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.
+      #
+      def logged_in?
+        user._logged_in?
+      end
+
+      ##
+      # Wrapper for the ever-present "user" in your application. It wraps
+      # around an arbitrary instance and worries about authentication and
+      # storing information about the user in the session.
+      #
+      # In order to not interfere with the wrapped instance/model we start our
+      # methods with an underscore.
+      #
+      # Patches and suggestions are highly appreciated.
+      #
+      class Wrapper < BlankSlate
+        attr_accessor :_model, :_callback, :_user
 
-        def initialize(model)
-          raise ArgumentError, "No model defined for Helper::User" unless model
-          @model = model
-          @user = nil
-          login(persist)
+        def initialize(model, callback)
+          @_model, @_callback = model, callback
+          @_user = nil
+          _login
         end
 
-        def logged_in?
-          !!@user
+        ##
+        # @author manveru
+        # @see    Ramaze::Helper::User#user_login
+        # @param  [Hash] creds this hash will be stored in the session on
+        #  successful login
+        # @return [Ramaze::Helper::User::Wrapper] wrapped return value from
+        #  model or callback
+        #
+        def _login(creds = nil)
+          if creds
+            if @_user = _would_login?(creds)
+              Current.session.resid!
+              self._persistence = {:credentials => creds}
+            end
+          elsif persistence = self._persistence
+            @_user = _would_login?(persistence[:credentials])
+          end
         end
 
-        def login?(hash)
-          credentials = {}
-          hash.each{|k,v| credentials[k.to_sym] = v.to_s }
-          @model[credentials]
+        ##
+        # The callback should return an instance of the user, otherwise it
+        # should answer with nil.
+        #
+        # This will not actually login, just check whether the credentials
+        # would result in a user.
+        #
+        def _would_login?(creds)
+          return unless creds
+
+          if c = @_callback
+            c.call(creds)
+          elsif _model.respond_to?(:authenticate)
+            _model.authenticate(creds)
+          else
+            Log.warn(
+              "Helper::User has no callback and there is no %p::authenticate" \
+                % _model
+            )
+
+            nil
+          end
         end
 
-        def persist
-          session[:USER] ||= {}
+        ##
+        # @author manveru
+        # @api    internal
+        # @see    Ramaze::Helper::User#user_logout
+        #
+        def _logout
+          (_persistence || {}).clear
+          Current.request.env['ramaze.helper.user'] = nil
+          Current.session.resid!
         end
 
-        def persist=(hash)
-          session[:USER] = hash
+        ##
+        # @author manveru
+        # @api    internal
+        # @see    Ramaze::Helper::User#logged_in?
+        # @return [true false] whether the current user is logged in.
+        #
+        def _logged_in?
+          !!_user
         end
 
-        def login(hash = Request.current.params)
-          return if hash.empty?
-          if found = login?(hash)
-            @user = found
-            self.persist = hash
-          end
+        def _persistence=(obj)
+          Current.session[:USER] = obj
         end
 
-        def logout
-          persist.clear
+        def _persistence
+          Current.session[:USER]
         end
 
+        ##
+        # Refer everything not known
+        # THINK: This might be quite confusing... should we raise instead?
+        #
         def method_missing(meth, *args, &block)
-          @user.send(meth, *args, &block)
+          return unless _user
+          _user.send(meth, *args, &block)
         end
       end
-    end
-  end
-end
+    end # User
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/xhtml.rb

@@ -0,0 +1,122 @@
+module Ramaze
+  module Helper
+
+    # Provides shortcuts to the link/script tags.
+    ##
+    # The XHTML helper can be used for generating CSS and Javascript tags.
+    # Generating a CSS tag can be done by calling the css() method:
+    #
+    #     css 'reset', 'screen', :only => 'ie'
+    #
+    # This would result in a stylesheet named "reset.css" being loaded only when
+    # the user is using Internet Explorer.
+    #
+    module XHTML
+      LINK_TAG = '<link href=%p media=%p rel="stylesheet" type="text/css" />'
+      SCRIPT_TAG = '<script src=%p type="text/javascript"></script>'
+
+      ##
+      # Generate a CSS tag based on the name, media type and a hash containing
+      # additional options. For example, if we want to load the stylesheet only
+      # when the user is using Internet Explorer we would have to add a key
+      # 'only' with a value of 'ie' to the hash.
+      #
+      # @param [String] name The name of the CSS file to load.
+      # @param [String] media The media type for which the stylesheet should be
+      #  loaded.
+      # @param [Hash] options A hash containing additional options for the
+      #  stylesheet tag.
+      # @example
+      #   # A very basic example.
+      #   css 'reset'
+      #
+      #   # Oh shiny, IE only
+      #   css 'reset', 'screen', :only => 'ie'
+      #
+      # @return [String] String containing the stylesheet tag.
+      #
+      def css(name, media = 'screen', options = {})
+        if media.respond_to?(:keys)
+          options = media
+          media = 'screen'
+        end
+
+        if only = options.delete(:only) and only.to_s == 'ie'
+          "<!--[if IE]>#{css(name, media, options)}<![endif]-->"
+        else
+          if name =~ /^http/
+            LINK_TAG % [name, media]
+          else
+            prefix = options[:prefix] || 'css'
+            LINK_TAG % [
+              "#{Ramaze.options.prefix.chomp("/")}/#{prefix}/#{name}.css",
+              media
+            ]
+          end
+        end
+      end
+
+      ##
+      # The css_for method can be used when you want to load multiple
+      # stylesheets and don't want to call the css() method over and over
+      # again.
+      #
+      # @example
+      #   # This is pretty basic
+      #   css_for 'reset', '960', 'style'
+      #
+      #   # Loading multiple stylesheets with custom options
+      #   css_for ['reset', 'print'], ['960', 'print']
+      #
+      # @see css()
+      # @param [Array] args An array containing either the names of all
+      #  stylesheets to load or a collection of arrays of which each array
+      #  defines the name, media and additional parameters.
+      # @return [String]
+      #
+      def css_for(*args)
+        args.map{|arg| css(*arg) }.join("\n")
+      end
+
+      ##
+      # Generates a Javascript tag that loads an external Javascript file. This
+      # tag can't be used for loading inline Javascript files.
+      #
+      # @example
+      #   # Simple isn't it?
+      #   js 'jquery'
+      #
+      #   # Let's change the directory to "some_other_directory"
+      #   js 'jquery', :prefix => 'some_other_directory'
+      #
+      # @param [String] name The name of the Javascript file that should be
+      #  loaded.
+      # @param [Hash] options Hash that can contain a :prefix key that defines
+      #  the directory in which the JS file is located. By default this key is
+      #  set to "js".
+      # @return [String]
+      #
+      def js(name, options={})
+        if name =~ /^http/ # consider it external full url
+          SCRIPT_TAG % name
+        else
+          SCRIPT_TAG % "#{Ramaze.options.prefix.chomp("/")}/#{options[:prefix] || 'js'}/#{name}.js"
+        end
+      end
+
+      ##
+      # Generate multiple Javascript tags using the js() method.
+      #
+      # @example
+      #   # Pretty simple isn't it?
+      #   js_for 'jquery', 'application', 'jquery.gritter'
+      #
+      # @param [Array] args Array containing the Javascript files to load.
+      # @return [String]
+      #
+      def js_for(*args)
+        args.map{|arg| js(*arg) }.join("\n")
+      end
+    end # XHTML
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper.rb

@@ -1,83 +1,12 @@
-#          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
-
-require 'ramaze/trinity'
+#          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
+# All files in this distribution are subject to the terms of the MIT license.
+require 'innate/helper'
 
 module Ramaze
+  Helper = Innate::Helper
+  Innate::HelpersHelper.options.paths << File.dirname(__FILE__)
 
-  # A module used by the Templates and the Controllers
-  # it provides both Ramaze::Trinity (request/response/session)
-  # and also a helper method, look below for more information about it
-
-  module Helper
-    LOOKUP = Set.new
-    trait :ignore => [
-      /#{Regexp.escape(File.expand_path(BASEDIR/'../spec/ramaze/helper/'))}\//
-    ]
-
-    module Methods
-      private
-
-      # This loads the helper-files from /ramaze/helper/helpername.rb and
-      # includes it into Ramaze::Template (or wherever it is called)
-      #
-      # Usage:
-      #   helper :redirect, :link
-
-      def helper(*syms)
-        syms.each do |sym|
-          name = sym.to_s
-          if mod = find_helper(name)
-            use_helper(mod)
-          else
-            if require_helper(name)
-              redo
-            else
-              raise LoadError, "#{name} not found"
-            end
-          end
-        end
-      end
-
-      # Will be going to be much simpler after deprecation *sigh*
-      def find_helper(name)
-        ramaze_helper_consts = ::Ramaze::Helper.constants.grep(/^#{name}$/i)
-        ramaze_consts = ::Ramaze.constants.grep(/^#{name}Helper$/i)
-        if mod_name = ramaze_helper_consts.first
-          ::Ramaze::Helper.const_get(mod_name)
-        elsif mod_name = ramaze_consts.first
-          mod = ::Ramaze.const_get(mod_name)
-          new_name = "Ramaze::Helper::" << mod_name.split('::').last[/^(.*)Helper$/, 1]
-          Log.warn "#{mod_name} is being deprecated, use #{new_name} instead"
-          mod
-        end
-      end
-
-      def require_helper(name)
-        glob = "{,#{APPDIR},#{BASEDIR/:ramaze}}/helper/#{name}.{so,bundle,rb}"
-        files = Dir[glob]
-        ignore = Helper.trait[:ignore]
-        files.reject!{|f| ignore.any?{|i| f =~ i }}
-        raise LoadError, "#{name} not found" unless file = files.first
-        require(file)
-      end
-
-      def use_helper(mod)
-        include mod
-        extend mod
-      end
-
-      def Methods.included other
-        other.send :extend, Trinity
-        other.send :include, Trinity
-        other.send :extend, Methods
-        super
-      end
-
-      def Methods.extend_object other
-        other.send :extend, Trinity
-        super
-      end
-    end
-  end
+  require 'ramaze/helper/flash'
+  require 'ramaze/helper/link'
+  require 'ramaze/helper/layout'
 end

data/lib/ramaze/log/hub.rb

@@ -1,38 +1,47 @@
 #          Copyright (c) 2008 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
-
-  # Bundles different informer instances and sends incoming messages to each.
-  # This is the default with Informer as only member.
-
-  class LogHub
-    include Logging
-
-    attr_accessor :loggers
-    attr_accessor :ignored_tags
-
-    # Takes a list of instances or classes (which will be initialized) and that
-    # are added to @loggers. All messages are then sent to each member.
-
-    def initialize(*loggers)
-      @loggers = loggers
-      @ignored_tags = Set.new
-      @loggers.map! do |logger|
-        next(nil) if logger == self
-        logger.is_a?(Class) ? logger.new : logger
+  module Logger
+    ##
+    # Bundles different informer instances and sends incoming messages to each.
+    # This is the default with Informer as only member.
+    #
+    class LogHub
+      include Logging
+
+      attr_accessor :loggers
+      attr_accessor :ignored_tags
+
+      ##
+      # Takes a list of instances or classes (which will be initialized) and that
+      # are added to @loggers. All messages are then sent to each member.
+      #
+      # @param [Array] loggers
+      #
+      def initialize(*loggers)
+        @loggers = loggers
+        @ignored_tags = Set.new
+        @loggers.map! do |logger|
+          next(nil) if logger == self
+          logger.is_a?(Class) ? logger.new : logger
+        end
+        @loggers.uniq!
+        @loggers.compact!
       end
-      @loggers.uniq!
-      @loggers.compact!
-    end
-
-    # integration to Logging
 
-    def log(tag, *args)
-      return if @ignored_tags.include?(tag)
-      @loggers.each do |logger|
-        logger.log(tag, *args)
+      ##
+      # Integration to Logging
+      #
+      # @param [String] tag
+      # @param [Hash] args
+      #
+      def log(tag, *args)
+        return if @ignored_tags.include?(tag)
+        @loggers.each do |logger|
+          logger.log(tag, *args)
+        end
       end
-    end
-  end
-end
+    end # Hub
+  end # log
+end # Ramaze