ioquatix-engines 2.1.0

data/lib/engines/load_engine_tasks.rake

@@ -0,0 +1,6 @@
+
+require RAILS_ROOT + "/config/environment"
+
+if defined? Engines
+  Engines.load_plugin_tasks
+end

data/lib/engines/plugin.rb

@@ -0,0 +1,173 @@
+# An instance of Plugin is created for each plugin loaded by Rails, and
+# stored in the <tt>Engines.plugins</tt> PluginList 
+# (see Engines::RailsExtensions::RailsInitializer for more details).
+#
+#   Engines.plugins[:plugin_name]
+#
+# If this plugin contains paths in directories other than <tt>app/controllers</tt>,
+# <tt>app/helpers</tt>, <tt>app/models</tt> and <tt>components</tt>, authors can
+# declare this by adding extra paths to #code_paths:
+#
+#    Rails.plugin[:my_plugin].code_paths << "app/sweepers" << "vendor/my_lib"
+#
+# Other properties of the Plugin instance can also be set.
+module Rails
+  class Plugin
+    # Plugins can add code paths to this attribute in init.rb if they 
+    # need plugin directories to be added to the load path, i.e.
+    #
+    #   plugin.code_paths << 'app/other_classes'
+    #
+    # Defaults to ["app/controllers", "app/helpers", "app/models", "components"]
+    attr_accessor :code_paths
+
+    # Plugins can add paths to this attribute in init.rb if they need
+    # controllers loaded from additional locations. 
+    attr_accessor :controller_paths
+  
+    # The directory in this plugin to mirror into the shared directory
+    # under +public+.
+    #
+    # Defaults to "assets" (see default_public_directory).
+    attr_accessor :public_directory
+    
+    protected
+    
+    def rails_path
+      File.join(directory, 'rails')
+    end
+    
+    # Helper
+    def rails_path_exists?(*args)
+      File.exists? File.join(rails_path, *args)
+    end
+    
+    def rails_plugin_root
+      if rails_path_exists?
+        rails_path
+      else
+        directory
+      end
+    end
+    
+    # The default set of code paths which will be added to $LOAD_PATH
+    # and Dependencies.load_paths
+    def default_code_paths
+      # lib will actually be removed from the load paths when we call
+      # uniq! in #inject_into_load_paths, but it's important to keep it
+      # around (for the documentation tasks, for instance).
+      %w(app/controllers app/helpers app/models components lib)
+    end
+  
+    # The default set of code paths which will be added to the routing system
+    def default_controller_paths
+      %w(app/controllers components)
+    end
+
+    # Attempts to detect the directory to use for public files.
+    # If +assets+ exists in the plugin, this will be used. If +assets+ is missing
+    # but +public+ is found, +public+ will be used.
+    def default_public_directory
+      Engines.select_existing_paths(%w(assets public).map { |p| File.join(rails_path, p) }).first
+    end
+  
+    alias_method :original_initialize, :initialize
+    alias_method :original_load, :load
+    
+    public
+    def initialize(*args)
+      original_initialize(*args)
+      
+      @code_paths = default_code_paths
+      @controller_paths = default_controller_paths
+      @public_directory = default_public_directory
+    end
+  
+    # Returns a list of paths this plugin wishes to make available in $LOAD_PATH
+    #
+    # Overwrites the correspondend method in the superclass
+    def load_paths
+      report_nonexistant_or_empty_plugin! unless valid?
+      select_existing_paths :code_paths
+    end
+    
+    # Extends the superclass' load method to additionally mirror public assets
+    
+    def load(*args)
+      return if loaded?
+      original_load(*args)
+      
+      add_plugin_view_paths
+      Engines::Assets.mirror_files_for(self)
+    end    
+  
+    # for code_paths and controller_paths select those paths that actually 
+    # exist in the plugin's directory
+    def select_existing_paths(name)
+      Engines.select_existing_paths(self.send(name).map { |p| File.join(rails_plugin_root, p) })
+    end    
+
+    def add_plugin_view_paths
+      view_path = File.join(rails_plugin_root, 'app', 'views')
+      if File.exist?(view_path)
+        ActionController::Base.view_paths.insert(1, view_path) # push it just underneath the app
+        ActionView::TemplateFinder.process_view_paths(view_path)
+      end
+    end
+
+    # The path to this plugin's public files
+    def public_asset_directory
+      "#{File.basename(Engines.public_directory)}/#{name}"
+    end
+    
+    # The path to this plugin's routes file
+    def routes_path
+      File.join(rails_plugin_root, 'routes.rb')
+    end
+    
+    def tasks_path
+      File.join(rails_plugin_root, 'tasks')
+    end
+    
+    # The directory containing this plugin's migrations (<tt>plugin/db/migrate</tt>)
+    def migration_directory
+      File.join(rails_plugin_root, 'db', 'migrate')
+    end
+  
+    # Returns the version number of the latest migration for this plugin. Returns
+    # nil if this plugin has no migrations.
+    def latest_migration
+      migrations.last
+    end
+    
+    # Returns the version numbers of all migrations for this plugin.
+    def migrations
+      migrations = Dir[migration_directory+"/*.rb"]
+      migrations.map { |p| File.basename(p).match(/0*(\d+)\_/)[1].to_i }.sort
+    end
+    
+    # Migrate this plugin to the given version. See Engines::Plugin::Migrator for more
+    # information.   
+    def migrate(version = nil)
+      Engines::Plugin::Migrator.migrate_plugin(self, version)
+    end
+    
+    class Loader
+      protected
+      alias_method :original_register_plugin_as_loaded, :register_plugin_as_loaded
+      def register_plugin_as_loaded(plugin)
+        original_register_plugin_as_loaded(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/list.rb

@@ -0,0 +1,57 @@
+# 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
+  module Plugin
+    class List
+      def initialize
+        @by_index = []
+        @by_symbol = {}
+        @by_string = {}
+      end
+      
+      # 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? Symbol
+          return @by_symbol[name_or_index]
+        elsif name_or_index.is_a? String
+          return @by_string[name_or_index]
+        else
+          return @by_index[name_or_index.to_i]
+        end
+      end
+      
+      attr :by_index
+      attr :by_symbol
+      attr :by_string
+      
+      def <<(plugin)
+        # Gemified plugins are sometimes username-plugin_name.
+        # We have to strip out username- so that canonical names work
+        # in this case.
+        sym_name = plugin.name.match(/([^-]+)$/)[1].to_sym
+        
+        @by_index << plugin
+        @by_symbol[sym_name] = plugin
+        @by_string[plugin.name] = plugin
+      end
+      
+      # Go through each plugin, highest priority first (last loaded first). Effectively,
+      # this is like <tt>Engines.plugins.reverse</tt>
+      def by_precedence
+        @by_index.reverse
+      end
+      
+      def method_missing(*args, &block)
+        @by_index.send(*args, &block)
+      end
+    end
+  end
+end

data/lib/engines/plugin/migrator.rb

@@ -0,0 +1,45 @@
+# 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
+module Engines
+  module Plugin
+    class Migrator < ActiveRecord::Migrator
+
+      # We need to be able to set the 'current' engine being migrated.
+      cattr_accessor :current_plugin
+  
+      class << self
+        # Runs the migrations from a plugin, up (or down) to the version given
+        def migrate_plugin(plugin, version)
+          self.current_plugin = plugin
+          return if current_version(plugin) == version
+          migrate(plugin.migration_directory, version)
+        end
+    
+        def current_version(plugin=current_plugin)
+          # Delete migrations that don't match .. to_i will work because the number comes first
+          ::ActiveRecord::Base.connection.select_values(
+            "SELECT version FROM #{schema_migrations_table_name}"
+          ).delete_if{ |v| v.match(/-#{plugin.name}/) == nil }.map(&:to_i).max || 0
+        end
+      end
+  
+      def migrated
+        sm_table = self.class.schema_migrations_table_name
+        ::ActiveRecord::Base.connection.select_values(
+          "SELECT version FROM #{sm_table}"
+        ).delete_if{ |v| v.match(/-#{current_plugin.name}/) == nil }.map(&:to_i).sort
+      end
+  
+      def record_version_state_after_migrating(version)
+        super(version.to_s + "-" + current_plugin.name)
+      end
+    end
+  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.unshift(*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,149 @@
+# 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
+
+  # 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
+
+  #--
+  # 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 : { }
+    result_paths = []
+    
+    if options.key? "plugin"
+      # Old method
+      sources.each do |s|
+        result_paths << plugin_asset_path(options["plugin"], type, s)
+      end
+      
+      options.delete "plugin"
+    else
+      # New method
+      sources.each do |s| 
+        if s.is_a? Array
+          plugin_name = s.shift
+          s.each { |p| result_paths += find_asset_paths(plugin_name, type, p) }
+        else
+          result_paths << s
+        end
+      end
+    end
+    result_paths << options # re-add options
+  end
+  
+  # This function can handle the case where asset == :all, and will return an array
+  def self.find_asset_paths(plugin_name, subdir, asset)
+    raise "No plugin called '#{plugin_name}' - please use the full name of a loaded plugin." if Engines.plugins[plugin_name].nil?
+    
+    asset_root = "/#{Engines.plugins[plugin_name].public_asset_directory}/#{type}"
+    
+    if asset == :all
+      Dir["#{asset_root}/*"]
+    else
+      ["#{asset_root}/#{asset}"]
+    end
+  end
+end
+
+module ::ActionView::Helpers::AssetTagHelper #:nodoc:
+  include Engines::RailsExtensions::AssetHelpers
+end