r3_plugin_toolbox 0.3.5 → 0.3.6

data/README.markdown

@@ -1,10 +1,15 @@
-# Rails 3 Plugin Toolbox
+
+# Rails3 Plugin Toolbox
 
 This is a small toolbox that greatly facilitates creating Plugins for Rails 3 without having to know a lot about the Rails 3 internals and Plugin architecture.
 The toolbox provides a convenient DSL that abstracts away the internal Rails 3 plugin wiring to an even greater extent, making the DSL dead simple to use!
 
 I also provide a specialized RSpec 2 matcher *be_extended_with* which makes it easy to spec your plugin extension functionality, to make sure Rails is extended with
-the functionality (modules) that you expect and desire ;)
+the functionality (modules) that you expect and desire ;) 
+
+Good description of the Rails 3 plugin structure on this gist by Jose Valim:
+
+_INFO_: [Rails 3 plugin architecture](https://gist.github.com/af7e572c2dc973add221)
 
 ## Install
 
@@ -18,7 +23,7 @@ the functionality (modules) that you expect and desire ;)
 require 'rails/all'
 require 'r3_plugin_toolbox'
 
-Rails3::PluginExtender.new do
+Rails3::Plugin::Extender.new do
   extend_from_module Ultra::View, :stuff, :in => :view 
   extend_with Ultra::Controller, :in => :controller
 
@@ -52,7 +57,7 @@ end
 More API examples
 
 <pre>                        
-Rails3::PluginExtender.new do  
+Rails3::Plugin::Extender.new do  
   extend_rails :view do # or use :action_view
     with MyViewAddition
   end
@@ -100,7 +105,7 @@ require 'rails/all'
 
 describe "My Plugin rails extensions" do
   it "should extend Action View with View Helpers" do
-    Rails3::PluginExtender.new do
+    Rails3::Plugin::Extender.new do
       extend_rails :view do          
         extend_from_module Helper::View, :panel, :window
         extend_with Helper::View::Button, Helper::View::Form
@@ -127,7 +132,7 @@ end
 
 describe "My other Plugin rails extensions" do
   before :each do
-    Rails3::PluginExtender.new do
+    Rails3::Plugin::Extender.new do
       extend_rails :view do          
         extend_from_module Helper::View, :grid, :tree      
       end        

data/Rakefile

@@ -9,6 +9,7 @@ begin
     gem.authors = ["Kristian Mandrup"]
     gem.add_development_dependency "rspec", "~> 2.0.0"
 
+    gem.add_development_dependency "rspec", ">= 2.0.0.beta.19"
     gem.add_dependency "rails",       "~> 3.0.0"
     gem.add_dependency "require_all", "~> 1.1.0"  
 

data/VERSION

@@ -1 +1 @@
-0.3.5
+0.3.6

data/lib/r3_plugin_toolbox.rb

@@ -4,4 +4,4 @@ end
 require 'active_support/inflector'
 require 'require_all'             
 
-require_all File.dirname(__FILE__) + '/plugin_toolbox'
+require_all File.dirname(__FILE__) + '/r3_plugin_toolbox'

data/lib/r3_plugin_toolbox/engine.rb

@@ -0,0 +1,77 @@
+# See: http://edgeapi.rubyonrails.org/classes/Rails/Engine.html
+
+# Any Rails::Engine is also a Rails::Railtie, so the same methods (like rake_tasks and generators) and configuration available in the latter can also be used in the former. 
+
+require 'r3_plugin_toolbox/railtie'
+
+def make_engine module_name
+  eval %{
+    module #{module_name}
+      class Engine < ::Rails::Engine            
+        extend ::Rails3::Engine::Assist
+      end
+    end        
+  }
+end  
+
+module Rails3
+  class Engine < ::Rails3::Plugin   
+    attr_reader :name    
+    
+    def initialize name, &block
+      @name = name
+      module_name = name.to_s.camelize
+      make_engine module_name
+      
+      engine = "#{module_name}::Engine".constantize
+      
+      if block
+        block.arity < 1 ? engine.instance_eval(&block) : block.call(engine)  
+      end
+    end  
+
+    module Assist   
+      include ::Rails3::Plugin::Assist
+      
+      [:autoload, :eagerload].each do |name|
+        class_eval %{
+          def add_#{name}_paths path
+            config.#{name}_paths << path
+          end          
+        }
+      end
+    
+      [:controllers, :helpers, :models, :views].each do |name|
+        class_eval %{
+          def add_#{name}_dir path
+            paths.app.#{name} << path
+          end
+        }
+      end    
+    
+      [:initializers, :locales, :routes].each do |name|
+        class_eval %{
+          def add_#{name}_dir path
+            paths.config.#{name} << path
+          end
+        }
+      end
+
+      def add_tasks_dir path
+        paths.lib.tasks << path
+      end
+    end
+  end
+end        
+
+# Example
+
+# class MyEngine < Rails::Engine
+#   # Add a load path for this specific Engine
+#   config.autoload_paths << File.expand_path("../lib/some/path", __FILE__)
+# 
+#   initializer "my_engine.add_middleware" do |app|
+#     app.middleware.use MyEngine::Middleware
+#   end
+# end
+

data/lib/r3_plugin_toolbox/extender.rb

@@ -0,0 +1,72 @@
+require 'r3_plugin_toolbox/extender/util'
+require 'r3_plugin_toolbox/extender/load_handler'
+
+module Rails3
+  class Plugin
+    class Extender
+      include LoadHandler
+   
+      def initialize &block
+        if block
+          block.arity < 1 ? self.instance_eval(&block) : block.call(self)  
+        end      
+      end
+
+      # load after: [:initialize, :configuration, :eager_load]
+      def extend_rails(type, &block)
+        on_load(type, &block)
+      end
+
+  
+      # convenience method to extend with multiple modules all within the same base module
+      def extend_from_module base_name, *module_names, options
+        raise ArgumentError, "You must specify an options Hash as the last argument for #extend_from_module" if !options.kind_of? Hash      
+        module_names.each do |name|
+          extend_with get_constant(base_name, name), options
+        end
+      end
+
+      def extend_with *module_names, options
+        raise ArgumentError, "You must specify an options Hash as the last argument for #extend_with" if !options.kind_of? Hash      
+        type = options[:in]
+        raise ArgumentError, "You must specify an :in option to indicate which Rails 3 component base class to extend with #{module_names}" if !type
+        module_names.each do |name|      
+          extend! name, type
+        end
+      end
+  
+      module DSL         
+        include ::Rails3::Plugin::Extender::LoadHandler      
+    
+        def extend_from_module base_name, *module_names
+          module_names.each do |name|
+            include get_constant(base_name, name)
+          end
+        end
+
+        def extend_with *module_names
+          module_names.each do |module_name|
+            begin
+              include get_module(module_name)
+            rescue
+              raise ArgumentError, "Unable to extend with #{module_name}"
+            end
+          end
+        end
+        alias_method :with, :extend_with
+      end
+
+      protected
+
+      def extend! module_name, type
+        do_extend! get_module(module_name), get_load_type(type.to_sym)
+      end
+
+      def do_extend! module_name, type
+        ActiveSupport.on_load(type) do
+          include module_name
+        end        
+      end
+    end
+  end
+end

data/lib/r3_plugin_toolbox/extender/load_handler.rb

@@ -0,0 +1,39 @@
+require 'r3_plugin_toolbox/extender/util'
+
+module Rails3
+  class Plugin
+    class Extender
+      module LoadHandler
+        include ::Rails3::Plugin::Extender::Util
+
+        def before type, &block
+          type = type.to_sym
+          raise ArgumentError, "#{type} is not a valid before hook" if !valid_before_hook? type
+          load_handling :"before_#{type}", &block
+        end
+
+        def after type, &block
+          type = type.to_sym
+          raise ArgumentError, "#{type} is not a valid after hook" if !valid_after_hook? type
+          load_handling :"after_#{type}", &block
+        end
+
+        def on_load type, &block    
+          type = get_load_type type
+          raise ArgumentError, "#{type} is not a valid load hook" if !valid_load_hook? type
+          load_handling type, &block
+        end
+      
+        def load_handling type, &block
+          ActiveSupport.on_load type do
+            extend Rails3::Plugin::Extender::DSL
+
+            if block
+              block.arity < 1 ? self.instance_eval(&block) : block.call(self)  
+            end      
+          end
+        end
+      end
+    end
+  end
+end

data/lib/r3_plugin_toolbox/extender/util.rb

@@ -0,0 +1,64 @@
+module Rails3
+  class Plugin
+    class Extender
+      module Util    
+        INIT = :initialize    
+        ACTIVE_MODULES = {:AR => :active_record, :view => :action_view, :controller => :action_controller, :mailer => :action_mailer}    
+
+        def get_base_class type
+          type = get_load_type(type).to_s
+          const = act_type?(type) ? rails_const_base(type) : "#{type.to_s.camelize}"                            
+        end
+
+        def act_type? type
+          type =~/action/ || type =~/active/        
+        end
+
+        def get_constant base_name, name   
+          make_constant(base_name, name).constantize
+        end
+
+        def rails_const_base type
+          "#{type.to_s.camelize}::Base"
+        end
+
+        def make_constant base_name, name
+          "#{base_name.to_s.camelize}::#{name.to_s.camelize}"
+        end
+
+        def get_load_type type
+           return ACTIVE_MODULES[type] if ACTIVE_MODULES[type]
+           return type if ACTIVE_MODULES.values.include? type                
+           return type if type == :i18n
+           logger.warn "WARNING: The Rails 3 load handler for the component #{type} is not part of the default load process."
+        end
+
+        def get_module module_name
+          case module_name
+          when Module        
+            module_name
+          when String
+            module_name.to_s.constantize
+          else          
+            raise ArgumentError, "#{module_name} could not be converted into a module constant"        
+          end
+        end
+
+        protected
+    
+        def valid_before_hook? type
+          [INIT, :configuration, :eager_load].include?(type)          
+        end
+
+        def valid_after_hook? type
+          INIT == type
+        end
+
+        def valid_load_hook? type
+          @valid_load_hooks ||= [ACTIVE_MODULES.keys, ACTIVE_MODULES.values, :i18n].flatten
+          @valid_load_hooks.include?(type)          
+        end    
+      end
+    end
+  end
+end

data/lib/r3_plugin_toolbox/main.rb

@@ -0,0 +1,5 @@
+require 'r3_plugin_toolbox/railtie'
+require 'r3_plugin_toolbox/extender'
+require 'r3_plugin_toolbox/engine'
+
+require_all File.dirname(__FILE__) + '/rspec'

data/lib/r3_plugin_toolbox/railtie.rb

@@ -0,0 +1,85 @@
+# See: http://edgeapi.rubyonrails.org/classes/Rails/Railtie.html
+
+# Add a to_prepare block which is executed once in production
+# and before each request in development
+# config.to_prepare do
+#   MyRailtie.setup!
+# end
+
+# rake_tasks do
+#   load "path/to/my_railtie.tasks"
+# end
+      
+# generators do
+#   require "path/to/my_railtie_generator"
+# end
+
+
+def make_railtie name
+  eval %{
+    module #{name.to_s.camelize}
+      class Railtie < Rails::Railtie
+        extend ::Rails3::Plugin::Assist
+      end
+    end
+  }
+end  
+
+module Rails3
+  class Plugin    
+    attr_reader :name 
+    
+    def initialize name, &block
+      @name = name
+
+      module_name = name.to_s.camelize
+      make_railtie module_name
+      
+      railtie = "#{module_name}::Railtie".constantize
+
+      if block
+        block.arity < 1 ? railtie.instance_eval(&block) : block.call(railtie)  
+      end      
+    end    
+
+    module Assist
+      def set_test_framework name
+        config.generators.test_framework name
+      end
+
+      def use_middleware middleware
+        app.middleware.use middleware
+      end
+
+      def set_orm orm_name
+        config.generators.orm(orm_name)
+      end      
+    
+      def subscribe_notifications *args, &block
+        ActiveSupport::Notifications.subscribe do |*args|
+          yield *args
+        end
+      end
+    end
+  end
+end
+
+# Example
+
+# module NewPlugin
+#   # namespace our plugin and inherit from Rails::Railtie
+#   # to get our plugin into the initialization process
+#   class Railtie < Rails::Railtie
+#  
+#     # configure our plugin on boot. other extension points such
+#     # as configuration, rake tasks, etc, are also available
+#     initializer "newplugin.initialize" do |app|
+#  
+#       # subscribe to all rails notifications: controllers, AR, etc.
+#       ActiveSupport::Notifications.subscribe do |*args|
+#         event = ActiveSupport::Notifications::Event.new(*args)
+#         puts "Got notification: #{event.inspect}"
+#       end 
+#     end
+#   end
+# end

data/lib/r3_plugin_toolbox/rspec/config.rb

@@ -0,0 +1,14 @@
+require 'rspec'
+require 'r3_plugin_toolbox/rspec/macro'
+require_all File.dirname(__FILE__) + '/matchers'
+
+RSpec.configure do |config|
+  config.include Rails3::Plugin::Extender::Matchers
+  config.extend Rails3::Plugin::Extender::Macro
+end
+
+module RSpec::Core
+  class ExampleGroup
+    include Rails3::Plugin::Extender::Macro
+  end
+end