ioquatix-engines 2.1.0

data/lib/engines/rails_extensions/dependencies.rb

@@ -0,0 +1,151 @@
+# 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
+
+if defined? ActiveSupport::Dependencies
+  module ActiveSupport::Dependencies #:nodoc:
+    include Engines::RailsExtensions::Dependencies
+  end
+else
+  module ::Dependencies
+    include Engines::RailsExtensions::Dependencies
+  end
+end

data/lib/engines/rails_extensions/routing.rb

@@ -0,0 +1,88 @@
+# Effective use of Rails' routes can help create a tidy and elegant set of URLs,
+# and is a significant part of creating an external API for your web application.
+# 
+# When developing plugins which contain controllers, it seems obvious that including
+# the corresponding routes would be extremely useful. This is particularly true
+# when exposing RESTful resources using the new REST-ian features of Rails.
+#
+# == Including routes in your plugin
+#
+# The engines plugin makes it possible to include a set of routes within your plugin
+# very simply, as it turns out. In your plugin, you simply include a <tt>routes.rb</tt> 
+# file like the one below at the root of your plugin:
+# 
+#   connect "/login", :controller => "my_plugin/account", :action => "login"
+#
+#   # add a named route
+#   logout "/logout", :controller => "my_plugin/account", :action => "logout"
+#
+#   # some restful stuff
+#   resources :things do |t|
+#     t.resources :other_things
+#   end
+# 
+# Everywhere in a normal <tt>RAILS_ROOT/config/routes.rb</tt> file 
+# where you might have <tt>map.connect</tt>, you just use <tt>connect</tt> in your 
+# plugin's <tt>routes.rb</tt>.
+# 
+# === Hooking it up in your application
+#
+# While it would be possible to have each plugin's routes automagically included into
+# the application's route set, to do so would actually be a stunningly bad idea. Route
+# priority is the key issue here. You, the application developer, needs to be in complete
+# control when it comes to specifying the priority of routes in your application, since 
+# the ordering of your routes directly affects how Rails will interpret incoming requests.
+# 
+# To add plugin routes into your application's <tt>routes.rb</tt> file, you need to explicitly 
+# map them in using the Engines::RailsExtensions::Routing#from_plugin method:
+# 
+#   ApplicationController::Routing::Routes.draw do |map|
+#
+#     map.connect "/app_stuff", :controller => "application_thing" # etc...
+#
+#     # This line includes the routes from the given plugin at this point, giving you
+#     # control over the priority of your application routes 
+#     map.from_plugin :your_plugin
+#
+#     map.connect ":controller/:action/:id"
+#   end
+# 
+# By including routes in plugins which have controllers, you can now share in a simple way 
+# a compact and elegant URL scheme which corresponds to those controllers.
+#
+# ---
+#
+# The Engines::RailsExtensions::Routing module defines extensions to Rails' 
+# routing (ActionController::Routing) mechanism such that routes can be loaded 
+# from a given plugin.
+#
+# The key method is Engines::RailsExtensions::Routing#from_plugin, which can be called 
+# within your application's <tt>config/routes.rb</tt> file to load plugin routes at that point.
+#
+
+module Engines
+  module RailsExtensions
+    module Routing
+      # Loads the set of routes from within a plugin and evaluates them at this
+      # point within an application's main <tt>routes.rb</tt> file.
+      #
+      # Plugin routes are loaded from <tt><plugin_root>/routes.rb</tt>.
+      def from_plugin(name)
+        map = self # to make 'map' available within the plugin route file
+        routes_path = Engines.plugins[name].routes_path
+        Engines.logger.debug "loading routes from #{routes_path}"
+        eval(IO.read(routes_path), binding, routes_path) if File.file?(routes_path)
+      end
+    end
+  end
+end
+
+module ::ActionController #:nodoc:
+  module Routing #:nodoc:
+    class RouteSet #:nodoc:
+      class Mapper #:nodoc:
+        include Engines::RailsExtensions::Routing
+      end
+    end
+  end
+end

data/lib/engines/testing.rb

@@ -0,0 +1,87 @@
+# Contains the enhancements to assist in testing plugins. See Engines::Testing
+# for more details.
+
+require 'test/unit'
+
+require 'tmpdir'
+require 'fileutils'
+
+# In most cases, Rails' own plugin testing mechanisms are sufficient. However, there
+# are cases where plugins can be given a helping hand in the testing arena. This module 
+# contains some methods to assist when testing plugins that contain fixtures.
+# 
+# == Fixtures and plugins
+#
+# Since Rails' own fixtures method is fairly strict about where files can be loaded from,
+# the simplest approach when running plugin tests with fixtures is to simply copy all
+# fixtures into a single temporary location and inform the standard Rails mechanism to
+# use this directory, rather than RAILS_ROOT/test/fixtures.
+#
+# The Engines::Testing#setup_plugin_fixtures method does this, copying all plugin fixtures
+# into the temporary location before and tests are performed. This behaviour is invoked
+# the the rake tasks provided by the Engines plugin, in the "test:plugins" namespace. If
+# necessary, you can invoke the task manually.
+#
+# If you wish to take advantage of this, add a call to the Engines::Testing.set_fixture_path
+# method somewhere before your tests (in a test_helper file, or above the TestCase itself).
+#
+# = Testing plugins
+#
+# Normally testing a plugin will require that Rails is loaded, unless you are including
+# a skeleton Rails environment or set of mocks within your plugin tests. If you require
+# the Rails environment to be started, you must ensure that this actually happens; while
+# it's not obvious, your tests do not automatically run with Rails loaded.
+#
+# The simplest way to setup plugin tests is to include a test helper with the following
+# contents:
+#
+#   # Load the normal Rails helper. This ensures the environment is loaded
+#   require File.expand_path(File.dirname(__FILE__) + '/../../../../test/test_helper')
+#   # Ensure that we are using the temporary fixture path
+#   Engines::Testing.set_fixture_path
+#
+# Then run tests using the provided tasks (<tt>test:plugins</tt>, or the tasks that the engines
+# plugin provides - <tt>test:plugins:units</tt>, etc.).
+#
+# Alternatively, you can explicitly load the environment by adpating the contents of the
+# default <tt>test_helper</tt>:
+#
+#   ENV["RAILS_ENV"] = "test"
+#   # Note that we are requiring config/environment from the root of the enclosing application.
+#   require File.expand_path(File.dirname(__FILE__) + "/../../../../config/environment")
+#   require 'test_help'
+#
+module Engines::Testing
+  mattr_accessor :temporary_fixtures_directory
+  self.temporary_fixtures_directory = FileUtils.mkdir_p(File.join(Dir.tmpdir, "rails_fixtures"))
+  
+  # Copies fixtures from plugins and the application into a temporary directory 
+  # (Engines::Testing.temporary_fixtures_directory). 
+  # 
+  # If a set of plugins is not given, fixtures are copied from all plugins in order 
+  # of precedence, meaning that plugins can 'overwrite' the fixtures of others if they are 
+  # loaded later; the application's fixtures are copied last, allowing any custom fixtures
+  # to override those in the plugins. If no argument is given, plugins are loaded via
+  # PluginList#by_precedence.
+  #
+  # This method is called by the engines-supplied plugin testing rake tasks
+  def self.setup_plugin_fixtures(plugins = Engines.plugins.by_precedence)
+    
+    # Copy all plugin fixtures, and then the application fixtures, into this directory
+    plugins.each do |plugin| 
+      plugin_fixtures_directory =  File.join(plugin.directory, "test", "fixtures")
+      if File.directory?(plugin_fixtures_directory)
+        Engines.mirror_files_from(plugin_fixtures_directory, self.temporary_fixtures_directory)
+      end
+    end
+    Engines.mirror_files_from(File.join(RAILS_ROOT, "test", "fixtures"),
+                              self.temporary_fixtures_directory)
+  end
+  
+  # Sets the fixture path used by Test::Unit::TestCase to the temporary
+  # directory which contains all plugin fixtures.
+  def self.set_fixture_path
+    Test::Unit::TestCase.fixture_path = self.temporary_fixtures_directory
+    $LOAD_PATH.unshift self.temporary_fixtures_directory
+  end
+end

data/lib/engines/version.rb

@@ -0,0 +1,10 @@
+
+module Engines
+  module VERSION #:nodoc:
+    MAJOR = 2
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/rails/init.rb

@@ -0,0 +1,6 @@
+# Only call Engines.init once, in the after_initialize block so that Rails
+# plugin reloading works when turned on
+
+config.after_initialize do
+  Engines.init if defined? :Engines
+end

data/tasks/engines.rake

@@ -0,0 +1,249 @@
+# This code lets us redefine existing Rake tasks, which is extremely
+# handy for modifying existing Rails rake tasks.
+# Credit for the original snippet of code goes to Jeremy Kemper
+# http://pastie.caboo.se/9620
+unless Rake::TaskManager.methods.include?('redefine_task')
+  module Rake
+    module TaskManager
+      def redefine_task(task_class, args, &block)
+        task_name, arg_names, deps = resolve_args([args])
+        task_name = task_class.scope_name(@scope, task_name)
+        deps = [deps] unless deps.respond_to?(:to_ary)
+        deps = deps.collect {|d| d.to_s }
+        task = @tasks[task_name.to_s] = task_class.new(task_name, self)
+        task.application = self
+        task.add_description(@last_description)
+        @last_description = nil
+        task.enhance(deps, &block)
+        task
+      end
+      
+    end
+    class Task
+      class << self
+        def redefine_task(args, &block)
+          Rake.application.redefine_task(self, [args], &block)
+        end
+      end
+    end
+  end
+end
+
+namespace :db do
+  namespace :migrate do
+    desc 'Migrate database and plugins to current status.'
+    task :all => [ 'db:migrate', 'db:migrate:plugins' ]
+    
+    desc 'Migrate plugins to current status.'
+    task :plugins => :environment do
+      Engines.plugins.each do |plugin|
+        next unless File.exists? plugin.migration_directory
+        puts "Migrating plugin #{plugin.name} ..."
+        plugin.migrate
+      end
+    end
+
+    desc 'For engines coming from Rails version < 2.0, you need to upgrade the schema info table'
+    task :upgrade_plugin_migrations => :environment do
+      # This task will upgrade Rails < 2.0, and also databases previously updated with
+      # db:migrate:fix_engines_migrations
+      
+      # Old table name
+      old_sm_table = ActiveRecord::Migrator.proper_table_name(Engines.schema_info_table)
+      
+      unless ActiveRecord::Base.connection.table_exists?(old_sm_table)
+        abort "Cannot find old migration table - assuming nothing needs to be done"
+      end
+      
+      # There are two forms of the engines schema info - pre-fix_plugin_migrations and post
+      # We need to figure this out before we continue.
+      
+      results = ActiveRecord::Base.connection.select_rows(
+        "SELECT version, plugin_name FROM #{old_sm_table}"
+      ).uniq
+      
+      def insert_new_version(plugin_name, version)
+        version_string = "#{version}-#{plugin_name}"
+        new_sm_table = ActiveRecord::Migrator.schema_migrations_table_name
+        
+        # Check if the row already exists for some reason - maybe run this task more than once.
+        return if ActiveRecord::Base.connection.select_rows("SELECT * FROM #{new_sm_table} WHERE version = #{version_string.dump}").size > 0
+        
+        puts "Inserting new version #{version} for plugin #{plugin_name}.."
+        ActiveRecord::Base.connection.insert("INSERT INTO #{new_sm_table} (version) VALUES (#{version_string.dump})")
+      end
+      
+      # We need to figure out if they already used "fix_plugin_migrations"
+      versions = {}
+      results.each do |r|
+        versions[r[1]] ||= []
+        versions[r[1]] << r[0].to_i
+      end
+      
+      if versions.values.find{ |v| v.size > 1 } == nil
+        puts "Fixing migration info"
+        # We only have one listed migration per plugin - this is pre-fix_plugin_migrations,
+        # so we build all versions required. In this case, all migrations should 
+        versions.each do |plugin_name, version|
+          version = version[0] # There is only one version
+          
+          # We have to make an assumption that numeric migrations won't get this long..
+          # I'm not sure if there is a better assumption, it should work in all
+          # current cases.. (touch wood..)
+          if version.to_s.size < "YYYYMMDDHHMMSS".size
+            # Insert version records for each migration
+            (1..version).each do |v|
+             insert_new_version(plugin_name, v)
+            end
+          else
+            # If the plugin is new-format "YYYYMMDDHHMMSS", we just copy it across... 
+            # The case in which this occurs is very rare..
+            insert_new_version(plugin_name, version)
+          end
+        end
+      else
+        puts "Moving migration info"
+        # We have multiple migrations listed per plugin - thus we can assume they have
+        # already applied fix_plugin_migrations - we just copy it across verbatim
+        versions.each do |plugin_name, version|
+          version.each { |v| insert_new_version(plugin_name, v) }
+        end
+      end
+      
+      puts "Migration info successfully migrated - removing old schema info table"
+      ActiveRecord::Base.connection.drop_table(old_sm_table)
+    end
+    
+    desc 'Migrate a specified plugin.'
+    task({:plugin => :environment}, :name, :version) do |task, args|
+      name = args[:name] || ENV['NAME']
+      if plugin = Engines.plugins[name]
+        version = args[:version] || ENV['VERSION']
+        puts "Migrating #{plugin.name} to " + (version ? "version #{version}" : 'latest version') + " ..."
+        plugin.migrate(version ? version.to_i : nil)
+      else
+        puts "Plugin #{name} does not exist."
+      end
+    end
+  end
+end
+
+
+namespace :db do  
+  namespace :fixtures do
+    namespace :plugins do
+      
+      desc "Load plugin fixtures into the current environment's database."
+      task :load => :environment do
+        require 'active_record/fixtures'
+        ActiveRecord::Base.establish_connection(RAILS_ENV.to_sym)
+        Dir.glob(File.join(RAILS_ROOT, 'vendor', 'plugins', ENV['PLUGIN'] || '**', 
+                 'test', 'fixtures', '*.yml')).each do |fixture_file|
+          Fixtures.create_fixtures(File.dirname(fixture_file), File.basename(fixture_file, '.*'))
+        end
+      end
+      
+    end
+  end
+end
+
+# this is just a modification of the original task in railties/lib/tasks/documentation.rake, 
+# because the default task doesn't support subdirectories like <plugin>/app or
+# <plugin>/component. These tasks now include every file under a plugin's code paths (see
+# Plugin#code_paths).
+namespace :doc do
+
+  plugins = FileList['vendor/plugins/**'].collect { |plugin| File.basename(plugin) }
+
+  namespace :plugins do
+
+    # Define doc tasks for each plugin
+    plugins.each do |plugin|
+      desc "Create plugin documentation for '#{plugin}'"
+      Rake::Task.redefine_task(plugin => :environment) do
+        plugin_base   = RAILS_ROOT + "/vendor/plugins/#{plugin}"
+        options       = []
+        files         = Rake::FileList.new
+        options << "-o doc/plugins/#{plugin}"
+        options << "--title '#{plugin.titlecase} Plugin Documentation'"
+        options << '--line-numbers' << '--inline-source'
+        options << '-T html'
+
+        # Include every file in the plugin's code_paths (see Plugin#code_paths)
+        if Engines.plugins[plugin]
+          files.include("#{plugin_base}/{#{Engines.plugins[plugin].code_paths.join(",")}}/**/*.rb")
+        end
+        if File.exists?("#{plugin_base}/README")
+          files.include("#{plugin_base}/README")    
+          options << "--main '#{plugin_base}/README'"
+        end
+        files.include("#{plugin_base}/CHANGELOG") if File.exists?("#{plugin_base}/CHANGELOG")
+
+        if files.empty?
+          puts "No source files found in #{plugin_base}. No documentation will be generated."
+        else
+          options << files.to_s
+          sh %(rdoc #{options * ' '})
+        end
+      end
+    end
+  end
+end
+
+
+
+namespace :test do
+  task :warn_about_multiple_plugin_testing_with_engines do
+    puts %{-~============== A Moste Polite Warninge ===========================~-
+
+You may experience issues testing multiple plugins at once when using
+the code-mixing features that the engines plugin provides. If you do
+experience any problems, please test plugins individually, i.e.
+
+  $ rake test:plugins PLUGIN=my_plugin
+
+or use the per-type plugin test tasks:
+
+  $ rake test:plugins:units
+  $ rake test:plugins:functionals
+  $ rake test:plugins:integration
+  $ rake test:plugins:all
+
+Report any issues on http://dev.rails-engines.org. Thanks!
+
+-~===============( ... as you were ... )============================~-}
+  end
+  
+  namespace :plugins do
+
+    desc "Run the plugin tests in vendor/plugins/**/test (or specify with PLUGIN=name)"
+    task :all => [:warn_about_multiple_plugin_testing_with_engines, 
+                  :units, :functionals, :integration]
+    
+    desc "Run all plugin unit tests"
+    Rake::TestTask.new(:units => :setup_plugin_fixtures) do |t|
+      t.pattern = "vendor/plugins/#{ENV['PLUGIN'] || "**"}/test/unit/**/*_test.rb"
+      t.verbose = true
+    end
+    
+    desc "Run all plugin functional tests"
+    Rake::TestTask.new(:functionals => :setup_plugin_fixtures) do |t|
+      t.pattern = "vendor/plugins/#{ENV['PLUGIN'] || "**"}/test/functional/**/*_test.rb"
+      t.verbose = true
+    end
+    
+    desc "Integration test engines"
+    Rake::TestTask.new(:integration => :setup_plugin_fixtures) do |t|
+      t.pattern = "vendor/plugins/#{ENV['PLUGIN'] || "**"}/test/integration/**/*_test.rb"
+      t.verbose = true
+    end
+
+    desc "Mirrors plugin fixtures into a single location to help plugin tests"
+    task :setup_plugin_fixtures => :environment do
+      Engines::Testing.setup_plugin_fixtures
+    end
+    
+    # Patch the default plugin testing task to have setup_plugin_fixtures as a prerequisite
+    Rake::Task["test:plugins"].prerequisites << "test:plugins:setup_plugin_fixtures"
+  end
+end