Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Toolbox to facilitate Rails 3 plugin development
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
lib
log
spec
wiki
.document
.gitignore
.rspec
LICENSE
README.markdown
Rakefile
VERSION
r3_plugin_toolbox.gemspec

README.markdown

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 ;)

Good description of the Rails 3 plugin structure on this gist by Jose Valim:

INFO: Rails 3 plugin architecture

Install

gem install r3_plugin_toolbox

Compatibility

This gem has only been tested with Rails 3 and Ruby 1.9.

Usage

# my_plugin/lib/my_plugin/rails/extensions.rb      

require 'rails/all'
require 'r3_plugin_toolbox'

Rails3::Plugin::Extender.new do
  extend_from_module Ultra::View, :stuff, :in => :view 
  extend_with Ultra::Controller, :in => :controller

  before :initialize do
    "Rails not yet initialized!"
  end      

  extend_rails :i18n do
    with MyAddition
    extend_from_module Ultra::Power, :util, :logging, :monitor

    before :initialize do
      MyOtherAddition.say 'before localized!'
    end      

    before :configuration do
      MyOtherAddition.configured = 'was configured!'      
    end

    before :eager_load do
      puts "before eager load!"
    end

    after :initialize do
      MyAddition.say 'localized!'
    end      
  end
end

More API examples

                        
Rails3::Plugin::Extender.new do  
  extend_rails :view do # or use :action_view
    with MyViewAddition
  end

  extend_rails :controller do # or use :action_mailer
    with MyViewAddition
  end

  extend_rails :mailer do # or use :action_mailer
    with MyMailAddition, 'MyOtherMailAddition'
  end

  extend_rails :AR do # active record
    with MyActiveRecordAddition
  end

  extend_rails :active_record do
    with MyExtraScopeHelpers
  end

  extend_rails(:controller) do
    extend_from_module Ultra::Power, :util, :logging, :monitor
    extend_from_module Ultra::Power::More, :extra, :stuff
  end  
  
  after(:initialize) do
    puts "Rails initialized!"
  end    
end

RSpec 2 matchers

The library comes with a special Matcher to facilitate making Rails 3 extension specs

  • be_extended_with module_name, *submodules

Usage example:

   
                   
require 'rspec'
require 'r3_plugin_toolbox'
require 'rails/all'  

describe "My Plugin rails extensions" do
  it "should extend Action View with View Helpers" 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
      end
    end

    after_init :view do
      :view.should be_extended_with Helper::View, :panel, :window, :button, :form
      :view.should_not be_extended_with Helper::View, :unknown
    end

    after_init :controller do
      :controller.should be_extended_with Helper::Controller, :stuff
      :controller.should_not be_extended_with My::Paginator
    end

    # first arg is the App name, the remaining symbols are 
    # the identifiers for which railties to initialize
    init_app_railties :minimal, :view, :controller
  end  
end

# alternative RSpec configuration using macros

describe "My other Plugin rails extensions" do
  before :each do
    Rails3::Plugin::Extender.new do
      extend_rails :view do          
        extend_from_module Helper::View, :grid, :tree      
      end        
    end
  end

  after_init :view do
    :view.should be_extended_with Helper::View, :panel, :window, :button, :form
  end

  it "should extend Action View" do      
    init_app_railties :minimal, :view
  end

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.

Something went wrong with that request. Please try again.