pager-engines 2.0.20080513

data/about.yml

@@ -0,0 +1,7 @@
+author: James Adam
+email: james.adam@gmail.com
+homepage: http://www.rails-engines.org
+summary: Enhances the plugin mechanism to perform more flexible sharing
+description: The Rails Engines plugin allows the sharing of almost any type of code or asset that you could use in a Rails application, including controllers, models, stylesheets, and views.
+license: MIT
+version: 2.0.0-RC1

data/boot.rb

@@ -0,0 +1,19 @@
+begin
+  require 'rails/version'
+  unless Rails::VERSION::MAJOR >= 2 ||
+         (Rails::VERSION::MAJOR >= 1 && Rails::VERSION::MINOR >= 99)
+    raise "This version of the engines plugin requires Rails 2.0 or later!"
+  end
+end
+
+require File.join(File.dirname(__FILE__), 'lib/engines')
+
+# initialize Rails::Configuration with our own default values to spare users 
+# some hassle with the installation and keep the environment cleaner
+
+{ :default_plugin_locators => [Engines::Plugin::FileSystemLocator,
+                              (Engines::Plugin::GemLocator if defined?(Gem))].compact , 
+  :default_plugin_loader => Engines::Plugin::Loader,
+  :default_plugins => [:engines, :all] }.each do |name, default|    
+  Rails::Configuration.send(:define_method, name) { default }
+end

data/generators/plugin_migration/USAGE

@@ -0,0 +1,45 @@
+Description:
+  The plugin migration generator assists in working with schema additions 
+  required by plugins. Instead of running migrations from plugins directly,
+  the generator creates a regular Rails migration which will be responsible
+  for migrating the plugins from their current version to the latest version
+  installed.
+  
+  This is important because the set of application migrations remains an
+  accurate record of the state of the database, even as plugins are installed
+  and removed during the development process.
+
+Example:
+  ./script/generate plugin_migration [<plugin_name> <another_plugin_name> ...]
+
+  This will generate:
+
+    RAILS_ROOT
+      |- db
+          |-migrate
+              |- xxx_plugin_migrations.rb
+
+  which contains the migrations for the given plugin(s).
+  
+  
+Advanced Usage:
+
+There may be situations where you need *complete* control over the migrations
+of plugins in your application, migrating a certainly plugin down to X, and
+another plugin up to Y, where neither X or Y are the latest migrations for those
+plugins.
+
+For those unfortunate few, I have two pieces of advice:
+
+ 1. Why? This is a code smell [http://c2.com/xp/CodeSmell.html].
+ 
+ 2. Well, OK. Don't panic. You can completely control plugin migrations by
+    creating your own migrations. To manually migrate a plugin to a specific
+    version, simply use
+    
+      Engines.plugins[:your_plugin_name].migrate(version)
+      
+    where version is the integer of the migration this plugin should end
+    up at.
+    
+With great power comes great responsibility. Use this wisely.

data/generators/plugin_migration/plugin_migration_generator.rb

@@ -0,0 +1,79 @@
+# Generates a migration which migrates all plugins to their latest versions
+# within the database.
+class PluginMigrationGenerator < Rails::Generator::Base
+  
+  def initialize(runtime_args, runtime_options={})
+    super
+    @options = {:assigns => {}}
+    
+    ensure_plugin_schema_table_exists
+    get_plugins_to_migrate(runtime_args)
+    
+    if @plugins_to_migrate.empty?
+      puts "All plugins are migrated to their latest versions"
+      exit(0)
+    end
+
+    @options[:migration_file_name] = build_migration_name
+    @options[:assigns][:class_name] = build_migration_name.classify
+  end
+  
+  def manifest
+    record do |m|
+      m.migration_template 'plugin_migration.erb', 'db/migrate', @options
+    end
+  end
+  
+  protected
+  
+    # Create the plugin schema table if it doesn't already exist. See
+    # Engines::RailsExtensions::Migrations#initialize_schema_migrations_table_with_engine_additions
+    def ensure_plugin_schema_table_exists
+      ActiveRecord::Base.connection.initialize_schema_migrations_table
+    end
+
+    # Determine all the plugins which have migrations that aren't present
+    # according to the plugin schema information from the database.
+    def get_plugins_to_migrate(plugin_names)
+
+      # First, grab all the plugins which exist and have migrations
+      @plugins_to_migrate = if plugin_names.empty?
+        Engines.plugins
+      else
+        plugin_names.map do |name| 
+          Engines.plugins[name] ? Engines.plugins[name] : raise("Cannot find the plugin '#{name}'")
+        end
+      end
+      
+      @plugins_to_migrate.reject! { |p| p.latest_migration.nil? }
+      
+      # Then find the current versions from the database    
+      @current_versions = {}
+      @plugins_to_migrate.each do |plugin|
+        @current_versions[plugin.name] = Engines::Plugin::Migrator.current_version(plugin)
+      end
+
+      # Then find the latest versions from their migration directories
+      @new_versions = {}      
+      @plugins_to_migrate.each do |plugin|
+        @new_versions[plugin.name] = plugin.latest_migration
+      end
+      
+      # Remove any plugins that don't need migration
+      @plugins_to_migrate.map { |p| p.name }.each do |name|
+        @plugins_to_migrate.delete(Engines.plugins[name]) if @current_versions[name] == @new_versions[name]
+      end
+      
+      @options[:assigns][:plugins] = @plugins_to_migrate
+      @options[:assigns][:new_versions] = @new_versions
+      @options[:assigns][:current_versions] = @current_versions
+    end
+
+    # Construct a unique migration name based on the plugins involved and the
+    # versions they should reach after this migration is run.
+    def build_migration_name
+      @plugins_to_migrate.map do |plugin| 
+        "#{plugin.name}_to_version_#{@new_versions[plugin.name]}" 
+      end.join("_and_")
+    end  
+end

data/generators/plugin_migration/templates/plugin_migration.erb

@@ -0,0 +1,13 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+  <%- plugins.each do |plugin| -%>
+    Engines.plugins["<%= plugin.name %>"].migrate(<%= new_versions[plugin.name] %>)
+  <%- end -%>
+  end
+
+  def self.down
+  <%- plugins.each do |plugin| -%>
+    Engines.plugins["<%= plugin.name %>"].migrate(<%= current_versions[plugin.name] %>)
+  <%- end -%>
+  end
+end

data/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/lib/engines.rb

@@ -0,0 +1,174 @@
+require 'active_support'
+require File.join(File.dirname(__FILE__), 'engines/plugin')
+require File.join(File.dirname(__FILE__), 'engines/plugin/list')
+require File.join(File.dirname(__FILE__), 'engines/plugin/loader')
+require File.join(File.dirname(__FILE__), 'engines/plugin/locator')
+require File.join(File.dirname(__FILE__), 'engines/assets')
+require File.join(File.dirname(__FILE__), 'engines/rails_extensions/rails')
+
+# == Parameters
+#
+# The Engines module has a number of public configuration parameters:
+#
+# [+public_directory+]  The directory into which plugin assets should be
+#                       mirrored. Defaults to <tt>RAILS_ROOT/public/plugin_assets</tt>.
+# [+schema_info_table+] The table to use when storing plugin migration 
+#                       version information. Defaults to +plugin_schema_info+.
+#
+# Additionally, there are a few flags which control the behaviour of
+# some of the features the engines plugin adds to Rails:
+#
+# [+disable_application_view_loading+] A boolean flag determining whether
+#                                      or not views should be loaded from 
+#                                      the main <tt>app/views</tt> directory.
+#                                      Defaults to false; probably only 
+#                                      useful when testing your plugin.
+# [+disable_application_code_loading+] A boolean flag determining whether
+#                                      or not to load controllers/helpers 
+#                                      from the main +app+ directory,
+#                                      if corresponding code exists within 
+#                                      a plugin. Defaults to false; again, 
+#                                      probably only useful when testing 
+#                                      your plugin.
+# [+disable_code_mixing+] A boolean flag indicating whether all plugin
+#                         copies of a particular controller/helper should 
+#                         be loaded and allowed to override each other, 
+#                         or if the first matching file should be loaded 
+#                         instead. Defaults to false.
+#
+module Engines
+  # The set of all loaded plugins
+  mattr_accessor :plugins
+  self.plugins = Engines::Plugin::List.new  
+  
+  # List of extensions to load, can be changed in init.rb before calling Engines.init
+  mattr_accessor :rails_extensions
+  self.rails_extensions = %w(action_mailer asset_helpers routing migrations dependencies)
+  
+  # The name of the public directory to mirror public engine assets into.
+  # Defaults to <tt>RAILS_ROOT/public/plugin_assets</tt>.
+  mattr_accessor :public_directory
+  self.public_directory = File.join(RAILS_ROOT, 'public', 'plugin_assets')
+
+  # The table in which to store plugin schema information. Defaults to
+  # "plugin_schema_info".
+  mattr_accessor :schema_info_table
+  self.schema_info_table = "plugin_schema_info"
+
+  #--
+  # These attributes control the behaviour of the engines extensions
+  #++
+  
+  # Set this to true if views should *only* be loaded from plugins
+  mattr_accessor :disable_application_view_loading
+  self.disable_application_view_loading = false
+  
+  # Set this to true if controller/helper code shouldn't be loaded 
+  # from the application
+  mattr_accessor :disable_application_code_loading
+  self.disable_application_code_loading = false
+  
+  # Set this ti true if code should not be mixed (i.e. it will be loaded
+  # from the first valid path on $LOAD_PATH)
+  mattr_accessor :disable_code_mixing
+  self.disable_code_mixing = false
+  
+  # This is used to determine which files are candidates for the "code
+  # mixing" feature that the engines plugin provides, where classes from
+  # plugins can be loaded, and then code from the application loaded
+  # on top of that code to override certain methods.
+  mattr_accessor :code_mixing_file_types
+  self.code_mixing_file_types = %w(controller helper)
+  
+  class << self
+    def init
+      load_extensions
+      Engines::Assets.initialize_base_public_directory
+    end
+    
+    def logger
+      RAILS_DEFAULT_LOGGER
+    end
+    
+    def load_extensions
+      rails_extensions.each { |name| require "engines/rails_extensions/#{name}" }
+      # load the testing extensions, if we are in the test environment.
+      require "engines/testing" if RAILS_ENV == "test"
+    end
+    
+    def select_existing_paths(paths)
+      paths.select { |path| File.directory?(path) }
+    end  
+  
+    # The engines plugin will, by default, mix code from controllers and helpers,
+    # allowing application code to override specific methods in the corresponding
+    # controller or helper classes and modules. However, if other file types should
+    # also be mixed like this, they can be added by calling this method. For example,
+    # if you want to include "things" within your plugin and override them from
+    # your applications, you should use the following layout:
+    #
+    #   app/
+    #    +-- things/
+    #    |       +-- one_thing.rb
+    #    |       +-- another_thing.rb
+    #   ...
+    #   vendor/
+    #       +-- plugins/
+    #                +-- my_plugin/
+    #                           +-- app/
+    #                                +-- things/
+    #                                        +-- one_thing.rb
+    #                                        +-- another_thing.rb
+    #
+    # The important point here is that your "things" are named <whatever>_thing.rb,
+    # and that they are placed within plugin/app/things (the pluralized form of 'thing').
+    # 
+    # It's important to note that you'll also want to ensure that the "things" are
+    # on your load path in your plugin's init.rb:
+    #
+    #   Rails.plugins[:my_plugin].code_paths << "app/things"
+    #
+    def mix_code_from(*types)
+      self.code_mixing_file_types += types.map { |x| x.to_s.singularize }
+    end
+    
+    # A general purpose method to mirror a directory (+source+) into a destination
+    # directory, including all files and subdirectories. Files will not be mirrored
+    # if they are identical already (checked via FileUtils#identical?).
+    def mirror_files_from(source, destination)
+      return unless File.directory?(source)
+      
+      # TODO: use Rake::FileList#pathmap?    
+      source_files = Dir[source + "/**/*"]
+      source_dirs = source_files.select { |d| File.directory?(d) }
+      source_files -= source_dirs
+      
+      unless source_files.empty?
+        base_target_dir = File.join(destination, File.dirname(source_files.first))
+        FileUtils.mkdir_p(base_target_dir)
+      end
+      
+      source_dirs.each do |dir|
+        # strip down these paths so we have simple, relative paths we can
+        # add to the destination
+        target_dir = File.join(destination, dir.gsub(source, ''))
+        begin        
+          FileUtils.mkdir_p(target_dir)
+        rescue Exception => e
+          raise "Could not create directory #{target_dir}: \n" + e
+        end
+      end
+      
+      source_files.each do |file|
+        begin
+          target = File.join(destination, file.gsub(source, ''))
+          unless File.exist?(target) && FileUtils.identical?(file, target)
+            FileUtils.cp(file, target)
+          end 
+        rescue Exception => e
+          raise "Could not copy #{file} to #{target}: \n" + e 
+        end
+      end  
+    end   
+  end  
+end

data/lib/engines/assets.rb

@@ -0,0 +1,38 @@
+module Engines
+  module Assets    
+    class << self      
+      @@readme = %{Files in this directory are automatically generated from your plugins.
+They are copied from the 'assets' directories of each plugin into this directory
+each time Rails starts (script/server, script/console... and so on).
+Any edits you make will NOT persist across the next server restart; instead you
+should edit the files within the <plugin_name>/assets/ directory itself.}     
+       
+      # Ensure that the plugin asset subdirectory of RAILS_ROOT/public exists, and
+      # that we've added a little warning message to instruct developers not to mess with
+      # the files inside, since they're automatically generated.
+      def initialize_base_public_directory
+        dir = Engines.public_directory
+        unless File.exist?(dir)
+          Engines.logger.debug "Creating public engine files directory '#{dir}'"
+          FileUtils.mkdir_p(dir)
+        end
+        readme = File.join(dir, "README")        
+        File.open(readme, 'w') { |f| f.puts @@readme } unless File.exist?(readme)
+      end
+    
+      # Replicates the subdirectories under the plugins's +assets+ (or +public+) 
+      # directory into the corresponding public directory. See also 
+      # Plugin#public_directory for more.
+      def mirror_files_for(plugin)
+        return if plugin.public_directory.nil?
+        begin 
+          Engines.logger.debug "Attempting to copy plugin assets from '#{plugin.public_directory}' to '#{Engines.public_directory}'"
+          Engines.mirror_files_from(plugin.public_directory, File.join(Engines.public_directory, plugin.name))      
+        rescue Exception => e
+          Engines.logger.warn "WARNING: Couldn't create the public file structure for plugin '#{plugin.name}'; Error follows:"
+          Engines.logger.warn e
+        end
+      end
+    end 
+  end
+end

data/lib/engines/plugin.rb

@@ -0,0 +1,142 @@
+# 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 Engines
+  module PluginExtension
+    def self.included(base)
+      # 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"]
+      base.send :attr_accessor, :code_paths
+
+      # Plugins can add paths to this attribute in init.rb if they need
+      # controllers loaded from additional locations. 
+      base.send :attr_accessor, :controller_paths
+
+      # The directory in this plugin to mirror into the shared directory
+      # under +public+.
+      #
+      # Defaults to "assets" (see default_public_directory).
+      base.send :attr_accessor, :public_directory
+      
+      base.alias_method_chain :initialize, :default_paths   
+    end
+
+    protected
+  
+      # 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(directory, p) }).first
+      end
+      
+      def initialize_default_paths
+        @code_paths = default_code_paths
+        @controller_paths = default_controller_paths
+        @public_directory = default_public_directory
+      end
+    
+    public
+    
+    def initialize_with_default_paths(*args)
+      initialize_without_default_paths(*args)
+      initialize_default_paths
+    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(initializer)
+      return if loaded?
+      super initializer
+      add_plugin_view_paths
+      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(directory, p) })
+    end    
+
+    def add_plugin_view_paths
+      view_path = File.join(directory, '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(directory, "routes.rb")
+    end
+
+    # The directory containing this plugin's migrations (<tt>plugin/db/migrate</tt>)
+    def migration_directory
+      File.join(self.directory, '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 = Dir[migration_directory+"/*.rb"]
+      return nil if migrations.empty?
+      migrations.map { |p| File.basename(p) }.sort.last.match(/0*(\d+)\_/)[1].to_i
+    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    
+  end
+  
+  class Plugin < Rails::Plugin    
+    include PluginExtension
+  end
+  
+  class GemPlugin < Rails::GemPlugin
+    include PluginExtension
+  end  
+end
+