pager-engines 2.0.20080513

data/lib/engines/plugin/list.rb

@@ -0,0 +1,30 @@
+# The PluginList class is an array, enhanced to allow access to loaded plugins
+# by name, and iteration over loaded plugins in order of priority. This array is used
+# by Engines::RailsExtensions::RailsInitializer to create the Engines.plugins array.
+#
+# Each loaded plugin has a corresponding Plugin instance within this array, and 
+# the order the plugins were loaded is reflected in the entries in this array.
+#
+# For more information, see the Rails module.
+module Engines
+  class Plugin
+    class List < Array
+      # Finds plugins with the set with the given name (accepts Strings or Symbols), or
+      # index. So, Engines.plugins[0] returns the first-loaded Plugin, and Engines.plugins[:engines]
+      # returns the Plugin instance for the engines plugin itself.
+      def [](name_or_index)
+        if name_or_index.is_a?(Fixnum)
+          super
+        else
+          self.find { |plugin| plugin.name.to_s == name_or_index.to_s }
+        end
+      end
+  
+      # Go through each plugin, highest priority first (last loaded first). Effectively,
+      # this is like <tt>Engines.plugins.reverse</tt>
+      def by_precedence
+        reverse
+      end
+    end
+  end
+end

data/lib/engines/plugin/loader.rb

@@ -0,0 +1,18 @@
+module Engines
+  class Plugin
+    class Loader < Rails::Plugin::Loader    
+      protected    
+        def register_plugin_as_loaded(plugin)
+          super plugin
+          Engines.plugins << plugin
+          register_to_routing(plugin)
+        end    
+        
+        # Registers the plugin's controller_paths for the routing system. 
+        def register_to_routing(plugin)
+          initializer.configuration.controller_paths += plugin.select_existing_paths(:controller_paths)
+          initializer.configuration.controller_paths.uniq!
+        end
+    end
+  end
+end

data/lib/engines/plugin/locator.rb

@@ -0,0 +1,37 @@
+module Engines
+  class Plugin
+    class FileSystemLocator < Rails::Plugin::FileSystemLocator
+      def create_plugin(path)
+        plugin = Engines::Plugin.new(path)
+        plugin.valid? ? plugin : nil
+      end        
+    end          
+    
+    # FIXME Rails GemLocator requires refactoring
+    class GemLocator < Rails::Plugin::GemLocator
+      def plugins
+        # FIXME think of it more
+        specs = initializer.configuration.gems.map(&:specification) + 
+                Gem.loaded_specs.values
+
+        # FIXME it should be in rails too
+        # Remove not installed gems specs to allow run rake gems:install
+        specs.compact!
+
+        # FIXME think of it more         
+        specs.reject! { |spec| !spec.loaded_from ||
+                               !File.exist?(File.join(spec.full_gem_path, "rails", "init.rb"))}
+
+        require "rubygems/dependency_list"
+
+        deps = Gem::DependencyList.new
+        deps.add(*specs) unless specs.empty?
+
+        deps.dependency_order.collect do |spec|
+          Engines::GemPlugin.new(spec)
+        end
+      end
+    end
+  end
+end
+

data/lib/engines/plugin/migrator.rb

@@ -0,0 +1,73 @@
+# The Plugin::Migrator class contains the logic to run migrations from
+# within plugin directories. The directory in which a plugin's migrations
+# should be is determined by the Plugin#migration_directory method.
+#
+# To migrate a plugin, you can simple call the migrate method (Plugin#migrate)
+# with the version number that plugin should be at. The plugin's migrations
+# will then be used to migrate up (or down) to the given version.
+#
+# For more information, see Engines::RailsExtensions::Migrations
+class Engines::Plugin::Migrator < ActiveRecord::Migrator
+
+  # We need to be able to set the 'current' engine being migrated.
+  cattr_accessor :current_plugin
+
+  # Runs the migrations from a plugin, up (or down) to the version given
+  def self.migrate_plugin(plugin, version)
+    self.current_plugin = plugin
+    # There seems to be a bug in Rails' own migrations, where migrating
+    # to the existing version causes all migrations to be run where that
+    # migration number doesn't exist (i.e. zero). We could fix this by
+    # removing the line if the version hits zero...?
+    return if current_version(plugin) == version
+    migrate(plugin.migration_directory, version)
+  end
+  
+  # Returns the name of the table used to store schema information about
+  # installed plugins.
+  #
+  # See Engines.schema_info_table for more details.
+  def self.schema_info_table_name
+    proper_table_name Engines.schema_info_table
+  end
+
+  # Returns the current version of the given plugin
+  def self.current_version(plugin=current_plugin)
+    result = ActiveRecord::Base.connection.select_one(<<-ESQL
+      SELECT version FROM #{schema_info_table_name} 
+      WHERE plugin_name = '#{plugin.name}'
+    ESQL
+    )
+    if result
+      result["version"].to_i
+    else
+      # There probably isn't an entry for this engine in the migration info table.
+      # We need to create that entry, and set the version to 0
+      ActiveRecord::Base.connection.execute(<<-ESQL
+        INSERT INTO #{schema_info_table_name} (version, plugin_name) 
+        VALUES (0,'#{plugin.name}')
+      ESQL
+      )      
+      0
+    end
+  end
+  
+  def migrated(plugin=current_plugin)
+    ActiveRecord::Base.connection.select_values(<<-ESQL
+      SELECT version FROM #{self.class.schema_info_table_name}
+      WHERE plugin_name = '#{plugin.name}'
+    ESQL
+    ).map(&:to_i).sort - [0]
+  end
+  
+  # Sets the version of the plugin in Engines::Plugin::Migrator.current_plugin to
+  # the given version.
+  def record_version_state_after_migrating(version)
+    ActiveRecord::Base.connection.update(<<-ESQL
+      UPDATE #{self.class.schema_info_table_name} 
+      SET version = #{down? ? version.to_i - 1 : version.to_i} 
+      WHERE plugin_name = '#{self.current_plugin.name}'
+    ESQL
+    )
+  end
+end

data/lib/engines/rails_extensions/action_mailer.rb

@@ -0,0 +1,85 @@
+# The way ActionMailer is coded in terms of finding templates is very restrictive, to the point
+# where all templates for rendering must exist under the single base path. This is difficult to
+# work around without re-coding significant parts of the action mailer code.
+#
+# ---
+#
+# The MailTemplates module overrides two (private) methods from ActionMailer to enable mail 
+# templates within plugins:
+#
+# [+template_path+]             which now produces the contents of #template_paths
+# [+initialize_template_class+] which now find the first matching template and creates 
+#                               an ActionVew::Base instance with the correct view_paths
+#
+# Ideally ActionMailer would use the same template-location logic as ActionView, and the same
+# view paths as ActionController::Base.view_paths, but it currently does not.
+module Engines::RailsExtensions::ActionMailer
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      # TODO commented this out because it seems to break ActionMailer
+      # how can this be fixed?
+      
+      alias_method_chain :template_path, :engine_additions
+      alias_method_chain :initialize_template_class, :engine_additions
+    end
+  end
+
+  private
+  
+    #--
+    # ActionMailer::Base#create uses two mechanisms to determine the proper template file(s)
+    # to load. Firstly, it searches within the template_root for files that much the explicit
+    # (or implicit) part encodings (like signup.text.plain.erb for the signup action). 
+    # This is how implicit multipart emails are built, by the way.
+    #
+    # Secondly, it then creates an ActionMailer::Base instance with it's view_paths parameter
+    # set to the template_root, so that ActionMailer will then take over rendering the
+    # templates.
+    #
+    # Ideally, ActionMailer would pass the same set of view paths as it gets in a normal
+    # request (i.e. ActionController::Base.view_paths), so that all possible view paths
+    # were searched. However, this seems to introduce some problems with helper modules.
+    #
+    # So instead, and because we have to fool these two independent parts of ActionMailer,
+    # we fudge with the mechanisms it uses to find the templates (via template_paths, and
+    # template_path_with_engine_additions), and then intercept the creation of the ActionView
+    # instance so we can set the view_paths (in initialize_template_class_with_engine_additions).
+    #++
+  
+    # Returns all possible template paths for the current mailer, including those
+    # within the loaded plugins.
+    def template_paths
+      paths = Engines.plugins.by_precedence.map { |p| "#{p.directory}/app/views/#{mailer_name}" }
+      paths.unshift(template_path_without_engine_additions) unless Engines.disable_application_view_loading
+      paths
+    end
+
+    # Return something that Dir[] can glob against. This method is called in 
+    # ActionMailer::Base#create! and used as part of an argument to Dir. We can
+    # take advantage of this by using some of the features of Dir.glob to search
+    # multiple paths for matching files.
+    def template_path_with_engine_additions
+      "{#{template_paths.join(",")}}"
+    end
+
+    # Return an instance of ActionView::Base with the view paths set to all paths
+    # in ActionController::Base.view_paths (i.e. including all plugin view paths)
+    def initialize_template_class_with_engine_additions(assigns)
+      # I'd like to just return this, but I get problems finding methods in helper
+      # modules if the method implemention from the regular class is not called
+      # 
+      # ActionView::Base.new(ActionController::Base.view_paths.dup, assigns, self)
+      renderer = initialize_template_class_without_engine_additions(assigns)
+      renderer.finder.view_paths = ActionController::Base.view_paths.dup
+      renderer
+    end
+end
+
+# We don't need to do this if ActionMailer hasn't been loaded.
+if Object.const_defined?(:ActionMailer) 
+  module ::ActionMailer #:nodoc:
+    class Base #:nodoc:
+      include Engines::RailsExtensions::ActionMailer
+    end
+  end
+end

data/lib/engines/rails_extensions/asset_helpers.rb

@@ -0,0 +1,119 @@
+# The engines plugin makes it trivial to share public assets using plugins. 
+# To do this, include an <tt>assets</tt> directory within your plugin, and put
+# your javascripts, stylesheets and images in subdirectories of that folder:
+#
+#   my_plugin
+#     |- init.rb
+#     |- lib/
+#     |- assets/
+#          |- javascripts/
+#          |    |- my_functions.js
+#          |
+#          |- stylesheets/
+#          |    |- my_styles.css
+#          |
+#          |- images/
+#               |- my_face.jpg
+#
+# Files within the <tt>asset</tt> structure are automatically mirrored into
+# a publicly-accessible folder each time your application starts (see
+# Engines::Assets#mirror_assets).
+#
+#
+# == Using plugin assets in views
+#
+# It's also simple to use Rails' helpers in your views to use plugin assets.
+# The default helper methods have been enhanced by the engines plugin to accept
+# a <tt>:plugin</tt> option, indicating the plugin containing the desired asset.
+#
+# For example, it's easy to use plugin assets in your layouts:
+#
+#   <%= stylesheet_link_tag "my_styles", :plugin => "my_plugin", :media => "screen" %>
+#   <%= javascript_include_tag "my_functions", :plugin => "my_plugin" %>
+# 
+# ... and similarly in views and partials, it's easy to use plugin images:
+#
+#   <%= image_tag "my_face", :plugin => "my_plugin" %>
+#   <!-- or -->
+#   <%= image_path "my_face", :plugin => "my_plugin" %>
+#
+# Where the default helpers allow the specification of more than one file (i.e. the
+# javascript and stylesheet helpers), you can do similarly for multiple assets from 
+# within a single plugin.
+#
+# ---
+#
+# This module enhances four of the methods from ActionView::Helpers::AssetTagHelper:
+#
+#  * stylesheet_link_tag
+#  * javascript_include_tag
+#  * image_path
+#  * image_tag
+#
+# Each one of these methods now accepts the key/value pair <tt>:plugin => "plugin_name"</tt>,
+# which can be used to specify the originating plugin for any assets.
+#
+module Engines::RailsExtensions::AssetHelpers
+  def self.included(base) #:nodoc:
+    base.class_eval do
+      [:stylesheet_link_tag, :javascript_include_tag, :image_path, :image_tag].each do |m|
+        alias_method_chain m, :engine_additions
+      end
+    end
+  end
+
+  # Adds plugin functionality to Rails' default stylesheet_link_tag method.
+  def stylesheet_link_tag_with_engine_additions(*sources)
+    stylesheet_link_tag_without_engine_additions(*Engines::RailsExtensions::AssetHelpers.pluginify_sources("stylesheets", *sources))
+  end
+
+  # Adds plugin functionality to Rails' default javascript_include_tag method.  
+  def javascript_include_tag_with_engine_additions(*sources)
+    javascript_include_tag_without_engine_additions(*Engines::RailsExtensions::AssetHelpers.pluginify_sources("javascripts", *sources))
+  end
+
+  #--
+  # Our modified image_path now takes a 'plugin' option, though it doesn't require it
+  #++
+
+  # Adds plugin functionality to Rails' default image_path method.
+  def image_path_with_engine_additions(source, options={})
+    options.stringify_keys!
+    source = Engines::RailsExtensions::AssetHelpers.plugin_asset_path(options["plugin"], "images", source) if options["plugin"]
+    image_path_without_engine_additions(source)
+  end
+
+  # Adds plugin functionality to Rails' default image_tag method.
+  def image_tag_with_engine_additions(source, options={})
+    options.stringify_keys!
+    if options["plugin"]
+      source = Engines::RailsExtensions::AssetHelpers.plugin_asset_path(options["plugin"], "images", source)
+      options.delete("plugin")
+    end
+    image_tag_without_engine_additions(source, options)
+  end
+
+  #--
+  # The following are methods on this module directly because of the weird-freaky way
+  # Rails creates the helper instance that views actually get
+  #++
+
+  # Convert sources to the paths for the given plugin, if any plugin option is given
+  def self.pluginify_sources(type, *sources)
+    options = sources.last.is_a?(Hash) ? sources.pop.stringify_keys : { }
+    sources.map! { |s| plugin_asset_path(options["plugin"], type, s) } if options["plugin"]
+    options.delete("plugin") # we don't want it appearing in the HTML
+    sources << options # re-add options      
+  end  
+
+  # Returns the publicly-addressable relative URI for the given asset, type and plugin
+  def self.plugin_asset_path(plugin_name, type, asset)
+    raise "No plugin called '#{plugin_name}' - please use the full name of a loaded plugin." if Engines.plugins[plugin_name].nil?
+    "/#{Engines.plugins[plugin_name].public_asset_directory}/#{type}/#{asset}"
+  end
+  
+end
+
+module ::ActionView::Helpers::AssetTagHelper #:nodoc:
+  include Engines::RailsExtensions::AssetHelpers
+end

data/lib/engines/rails_extensions/dependencies.rb

@@ -0,0 +1,145 @@
+# One of the magic features that that engines plugin provides is the ability to
+# override selected methods in controllers and helpers from your application.
+# This is achieved by trapping requests to load those files, and then mixing in
+# code from plugins (in the order the plugins were loaded) before finally loading
+# any versions from the main +app+ directory.
+#
+# The behaviour of this extension is output to the log file for help when
+# debugging.
+#
+# == Example
+#
+# A plugin contains the following controller in <tt>plugin/app/controllers/my_controller.rb</tt>:
+#
+#   class MyController < ApplicationController
+#     def index
+#       @name = "HAL 9000"
+#     end
+#     def list
+#       @robots = Robot.find(:all)
+#     end
+#   end
+#
+# In one application that uses this plugin, we decide that the name used in the
+# index action should be "Robbie", not "HAL 9000". To override this single method,
+# we create the corresponding controller in our application 
+# (<tt>RAILS_ROOT/app/controllers/my_controller.rb</tt>), and redefine the method:
+#
+#   class MyController < ApplicationController
+#     def index
+#       @name = "Robbie"
+#     end
+#   end
+#
+# The list method remains as it was defined in the plugin controller.
+#
+# The same basic principle applies to helpers, and also views and partials (although
+# view overriding is performed in Engines::RailsExtensions::Templates; see that
+# module for more information).
+#
+# === What about models?
+#
+# Unfortunately, it's not possible to provide this kind of magic for models.
+# The only reason why it's possible for controllers and helpers is because
+# they can be recognised by their filenames ("whatever_controller", "jazz_helper"),
+# whereas models appear the same as any other typical Ruby library ("node",
+# "user", "image", etc.). 
+#
+# If mixing were allowed in models, it would mean code mixing for *every* 
+# file that was loaded via +require_or_load+, and this could result in
+# problems where, for example, a Node model might start to include 
+# functionality from another file called "node" somewhere else in the
+# <tt>$LOAD_PATH</tt>.
+#
+# One way to overcome this is to provide model functionality as a module in
+# a plugin, which developers can then include into their own model
+# implementations.
+#
+# Another option is to provide an abstract model (see the ActiveRecord::Base
+# documentation) and have developers subclass this model in their own
+# application if they must.
+#
+# ---
+#
+# The Engines::RailsExtensions::Dependencies module includes a method to
+# override Dependencies.require_or_load, which is called to load code needed
+# by Rails as it encounters constants that aren't defined.
+#
+# This method is enhanced with the code-mixing features described above.
+#
+module Engines::RailsExtensions::Dependencies
+  def self.included(base) #:nodoc:
+    base.class_eval { alias_method_chain :require_or_load, :engine_additions }
+  end
+
+  # Attempt to load the given file from any plugins, as well as the application.
+  # This performs the 'code mixing' magic, allowing application controllers and
+  # helpers to override single methods from those in plugins.
+  # If the file can be found in any plugins, it will be loaded first from those
+  # locations. Finally, the application version is loaded, using Ruby's behaviour
+  # to replace existing methods with their new definitions.
+  #
+  # If <tt>Engines.disable_code_mixing == true</tt>, the first controller/helper on the
+  # <tt>$LOAD_PATH</tt> will be used (plugins' +app+ directories are always lower on the
+  # <tt>$LOAD_PATH</tt> than the main +app+ directory).
+  #
+  # If <tt>Engines.disable_application_code_loading == true</tt>, controllers will
+  # not be loaded from the main +app+ directory *if* they are present in any
+  # plugins.
+  #
+  # Returns true if the file could be loaded (from anywhere); false otherwise -
+  # mirroring the behaviour of +require_or_load+ from Rails (which mirrors
+  # that of Ruby's own +require+, I believe).
+  def require_or_load_with_engine_additions(file_name, const_path=nil)
+    return require_or_load_without_engine_additions(file_name, const_path) if Engines.disable_code_mixing
+
+    file_loaded = false
+
+    # try and load the plugin code first
+    # can't use model, as there's nothing in the name to indicate that the file is a 'model' file
+    # rather than a library or anything else.
+    Engines.code_mixing_file_types.each do |file_type| 
+      # if we recognise this type
+      # (this regexp splits out the module/filename from any instances of app/#{type}, so that
+      #  modules are still respected.)
+      if file_name =~ /^(.*app\/#{file_type}s\/)?(.*_#{file_type})(\.rb)?$/
+        base_name = $2
+        # ... go through the plugins from first started to last, so that
+        # code with a high precedence (started later) will override lower precedence
+        # implementations
+        Engines.plugins.each do |plugin|
+          plugin_file_name = File.expand_path(File.join(plugin.directory, 'app', "#{file_type}s", base_name))
+          Engines.logger.debug("checking plugin '#{plugin.name}' for '#{base_name}'")
+          if File.file?("#{plugin_file_name}.rb")
+            Engines.logger.debug("==> loading from plugin '#{plugin.name}'")
+            file_loaded = true if require_or_load_without_engine_additions(plugin_file_name, const_path)
+          end
+        end
+    
+        # finally, load any application-specific controller classes using the 'proper'
+        # rails load mechanism, EXCEPT when we're testing engines and could load this file
+        # from an engine
+        if Engines.disable_application_code_loading
+          Engines.logger.debug("loading from application disabled.")
+        else
+          # Ensure we are only loading from the /app directory at this point
+          app_file_name = File.join(RAILS_ROOT, 'app', "#{file_type}s", "#{base_name}")
+          if File.file?("#{app_file_name}.rb")
+            Engines.logger.debug("loading from application: #{base_name}")
+            file_loaded = true if require_or_load_without_engine_additions(app_file_name, const_path)
+          else
+            Engines.logger.debug("(file not found in application)")
+          end
+        end        
+      end 
+    end
+
+    # if we managed to load a file, return true. If not, default to the original method.
+    # Note that this relies on the RHS of a boolean || not to be evaluated if the LHS is true.
+    file_loaded || require_or_load_without_engine_additions(file_name, const_path)
+  end  
+end
+
+module ::Dependencies #:nodoc:
+  include Engines::RailsExtensions::Dependencies
+end