pager-engines 2.0.20080513

data/lib/engines/rails_extensions/migrations.rb

@@ -0,0 +1,161 @@
+# Contains the enhancements to Rails' migrations system to support the 
+# Engines::Plugin::Migrator. See Engines::RailsExtensions::Migrations for more
+# information.
+
+require "engines/plugin/migrator"
+
+# = Plugins and Migrations: Background
+#
+# Rails uses migrations to describe changes to the databases as your application
+# evolves. Each change to your application - adding and removing models, most
+# commonly - might require tweaks to your schema in the form of new tables, or new
+# columns on existing tables, or possibly the removal of tables or columns. Migrations
+# can even include arbitrary code to *transform* data as the underlying schema
+# changes.
+# 
+# The point is that at any particular stage in your application's development, 
+# migrations serve to transform the database into a state where it is compatible
+# and appropriate at that time.
+# 
+# == What about plugins?
+# 
+# If you want to share models using plugins, chances are that you might also
+# want to include the corresponding migrations to create tables for those models.
+# With the engines plugin installed, plugins can carry migration data easily:
+# 
+#   vendor/
+#     |
+#     plugins/
+#       |
+#       my_plugin/
+#         |- init.rb
+#         |- lib/
+#         |- db/
+#             |-migrate/
+#                 |- 001_do_something.rb
+#                 |- 002_and_something_else.rb
+#                 |- ...
+# 
+# When you install a plugin which contains migrations, you are undertaking a
+# further step in the development of your application, the same as the addition
+# of any other code. With this in mind, you may want to 'roll back' the
+# installation of this plugin at some point, and the database should be able
+# to migrate back to the point without this plugin in it too.
+#
+# == An example
+#
+# For example, our current application is at version 14 (according to the
+# +schema_info+ table), when we decide that we want to add a tagging plugin. The
+# tagging plugin chosen includes migrations to create the tables it requires
+# (say, _tags_ and _taggings_, for instance), along with the models and helpers
+# one might expect.
+#
+# After installing this plugin, these tables should be created in our database.
+# Rather than running the migrations directly from the plugin, they should be
+# integrated into our main migration stream in order to accurately reflect the
+# state of our application's database *at this moment in time*.
+#
+#   $ script/generate plugin_migration
+#         exists  db/migrate
+#         create  db/migrate/015_migrate_tagging_plugin_to_version_3.rb
+#
+# This migration will take our application to version 15, and contains the following, 
+# typical migration code:
+# 
+#   class MigrateTaggingPluginToVersion3 < ActiveRecord::Migration
+#     def self.up
+#       Engines.plugins[:tagging].migrate(3)
+#     end
+#     def self.down
+#       Engines.plugins[:tagging].migrate(0)
+#     end
+#   end
+#
+# When we migrate our application up, using <tt>rake db:migrate</tt> as normal,
+# the plugin will be migrated up to its latest version (3 in this example). If we
+# ever decide to migrate the application back to the state it was in at version 14,
+# the plugin migrations will be taken back down to version 0 (which, typically,
+# would remove all tables the plugin migrations define).
+#
+# == Upgrading plugins
+#
+# It might happen that later in an application's life, we update to a new version of
+# the tagging plugin which requires some changes to our database. The tagging plugin
+# provides these changes in the form of its own migrations. 
+#
+# In this case, we just need to re-run the plugin_migration generator to create a 
+# new migration from the current revision to the newest one:
+#
+#   $ script/generate plugin_migration
+#        exists db/migrate
+#        create db/migrate/023_migrate_tagging_plugin_to_version_5.rb
+#
+# The contents of this migration are:
+#
+#   class MigrateTaggingPluginToVersion3 < ActiveRecord::Migration
+#     def self.up
+#       Engines.plugins[:tagging].migrate(5)
+#     end
+#     def self.down
+#       Engines.plugins[:tagging].migrate(3)
+#     end
+#   end
+#
+# Notice that if we were to migrate down to revision 22 or lower, the tagging plugin
+# will be migrated back down to version 3 - the version we were previously at.
+#
+#
+# = Creating migrations in plugins
+#
+# In order to use the plugin migration functionality that engines provides, a plugin 
+# only needs to provide regular migrations in a <tt>db/migrate</tt> folder within it.
+#
+# = Explicitly migrating plugins
+#
+# It's possible to migrate plugins within your own migrations, or any other code.
+# Simply get the Plugin instance, and its Plugin#migrate method with the version
+# you wish to end up at:
+#
+#   Engines.plugins[:whatever].migrate(version)
+#
+# ---
+#
+# The Engines::RailsExtensions::Migrations module defines extensions for Rails' 
+# migration systems. Specifically:
+#
+# * Adding a hook to initialize_schema_migrations_table to create the plugin schema
+#   info table.
+#
+module Engines::RailsExtensions::Migrations
+  def self.included(base) # :nodoc:
+    base.class_eval { alias_method_chain :initialize_schema_migrations_table, :engine_additions }
+  end
+
+  # Create the schema tables, and ensure that the plugin schema table
+  # is also initialized. The plugin schema info table is defined by
+  # Engines::Plugin::Migrator.schema_info_table_name.
+  def initialize_schema_migrations_table_with_engine_additions
+    initialize_schema_migrations_table_without_engine_additions
+
+    # create the plugin schema stuff.    
+    begin
+      execute <<-ESQL
+        CREATE TABLE #{Engines::Plugin::Migrator.schema_info_table_name} 
+          (plugin_name #{type_to_sql(:string)}, version #{type_to_sql(:integer)})
+      ESQL
+    rescue ActiveRecord::StatementInvalid
+      # Schema has been initialized
+    end
+  end
+end
+
+module ::ActiveRecord #:nodoc:
+  module ConnectionAdapters #:nodoc:
+    module SchemaStatements #:nodoc:
+      include Engines::RailsExtensions::Migrations
+    end
+  end
+end
+
+# Set ActiveRecord to ignore the plugin schema table by default
+::ActiveRecord::SchemaDumper.ignore_tables << Engines.schema_info_table

data/lib/engines/rails_extensions/rails.rb

@@ -0,0 +1,11 @@
+# This is only here to allow for backwards compability with Engines that
+# have been implemented based on Engines for Rails 1.2. It is preferred that
+# the plugin list be accessed via Engines.plugins.
+
+module Rails
+  # Returns the Engines::Plugin::List from Engines.plugins. It is preferable to
+  # access Engines.plugins directly.
+  def self.plugins
+    Engines.plugins
+  end
+end

data/lib/engines/rails_extensions/routing.rb

@@ -0,0 +1,84 @@
+# 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::RailsExtensions::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
+
+  
+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_initializer.rb

@@ -0,0 +1,5 @@
+load "#{File.dirname(__FILE__)}/../boot.rb"
+
+Rails::Configuration.send(:undef_method, :default_plugins)
+Rails::Configuration.send(:define_method, :default_plugins) { ['pager-engines'.to_sym, :all] }
+

data/rails/init.rb

@@ -0,0 +1,5 @@
+# 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,179 @@
+# 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, 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 '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