Demystifying Rails Plugin Development

Transcription

1 Demystifying Rails Plugin Development Nick Plante :: Voices That Matter Professional Ruby Conference November 18th, 2008

2 Obligatory Introduction Plugins are generalized, reusable code libraries Ext or override core functionality of Rails Can save you a lot of time Provide standard hooks, helpers Rails scripts, hooks Generators, etc

3 vs. core plugin

4 but more like

5 Plugin Examples User Authentication Restful Authentication, Closure Pagination Will Paginate, Paginating Find Asynchronous Processing Workling, Background Job, etc View Helpers Lightbox helper, Flash media player helper, etc

6 Why Develop Plugins? Internal re-use, productivity booster Opportunity to refactor, clean up project code is_rateable vs. gobs of in-line ratings code Contribute to the Ruby OSS ecosystem Get feedback, contributions, inspire others Profit^h^h^h^h^h^h Marketing

7 Is Plugin Development Hard? Is developing software in Ruby/Rails hard? Deps on what you re trying to accomplish, right? The plugins system itself is simple Writing plugins can be hard, but it doesn t have to be

8 Plugin Genesis: Extraction Most plugins don t start out as plugins Usually extracted & generalized from a useful feature created in a larger project What interesting problems have you solved lately?

9 Validating ISBNs How would we implement this in a Book model for a plain old Rails project? ISBN-13: ISBN-10:

10 class Book < ActiveRecord::Base validates_presence_of :title, :author, :isbn def validate unless self.isbn_valid? errors.add(:isbn, "is not a valid ISBN code") ISBN10_REGEX = /^(?:\d[\ -]?){9}[\d X]$/ ISBN13_REGEX = /^(?:\d[\ -]?){13}$/ def isbn_valid?!self.isbn.nil? && (self.isbn10_valid? self.isbn13_valid?) #...

11 Wait! There s More!

12 # more code in your model def isbn10_valid? if self.isbn.match(isbn10_regex) isbn_values = self.isbn.upcase.gsub(/\ -/, '').split('') check_digit = isbn_values.pop # last digit is check check_digit = (check_digit == 'X')? 10 : check_digit.to_i sum = 0 isbn_values.each_with_index do value, index sum += (index + 1) * value.to_i (sum % 11) == check_digit else false

13 # and yet more code in your model def isbn13_valid? if self.isbn.match(isbn13_regex) isbn_values = self.isbn.upcase.gsub(/\ -/, '').split('') check_digit = isbn_values.pop.to_i # last digit is check sum = 0 isbn_values.each_with_index do value, index multiplier = (index % 2 == 0)? 1 : 3 sum += multiplier * value.to_i (10 - (sum % 10)) == check_digit else false

14 Your Model Code

15 Either way, we need to build a validation module, right? Extract! Let s clean up that messy model Encapsulation & Information Hiding Makes our model easier to read We can move this code to a module in lib Or yank it all out into a plugin!

16 Encapsulation

17 Designing the Interface We need a clean interface DON T judge a book by its cover But DO judge a plugin by its interface KISS -- there is beauty in simplicity / minimalism Goal is often to ext the Rails DSL in a natural way We have pre-existing examples to guide our hand ActiveRecord::Validations (see api.rubyonrails.org)

18 ActiveRecord Examples acts_as_list :scope => :todo_list validates_http_url :link is_indexed :fields => ['created_at', 'title ] has_attached_file :cover_image, :styles => { :medium => "300x300>", :thumb => "100x100> }

19 ActionController Examples class BooksController < ApplicationController sidebar :login, :unless => :logged_in? permit "rubyists and wanna_be_rubyists" include SomePluginModule def = Book.paginate :page => params[:page], :per_page => 20

20 ActionView Examples (View Helpers) <%= lightbox_link_to My Link, image.png %>

21 A Little Cleaner, Right? Yeah. class Book < ActiveRecord::Base validates_isbn :isbn, :with => :isbn13, :unless => :skip_validation

22

23 validates_isbn We need to create a validates_isbn class method on ActiveRecord::Base Generalize our code a bit No longer married to a particular model attribute Hide it behind a Rails-ish DSL Ext AR::Base with our own module

24 module IsbnValidation # may want to namespace this def validates_isbn(*attr_names) config = { :message => "is not a valid ISBN code" } config.update(attr_names.extract_options!) validates_each(attr_names, config) do record,attr_name,value valid = case config[:with] when :isbn10; validate_with_isbn10(value) when :isbn13; validate_with_isbn13(value) else validate_with_isbn10(value) validate_with_isbn13(value) record.errors.add(attr_name, config[:message]) unless valid # other methods, constants go here too

25 Making of the Module Why is it a module, and not a class? A module is like a degenerate abstract class You can mix a module into a class Include with a module to add instance methods Ext with a module to add class methods Also use modules for organization Group similar things together, namespacing

26 Mixing It Up with Modules Don t have to stash this module in a plugin Can use it directly from lib, too require isbn_validation class Book < ActiveRecord::Base ext IsbnValidation validates_isbn :isbn

27 Pluginizing But why not go the extra step? So you can easily reuse it across projects And share with others

28 Generate a Plugin Skeleton Use the supplied plugin generator The less we have to do, the better!

29 $ ruby script/generate plugin isbn_validation in vor/plugins/isbn_validation: - lib/ - isbn_validation.rb - tasks/ - isbn_validation_tasks.rake - test/ - isbn_validation_test.rb - README - MIT-LICENSE - Rakefile - init.rb - install.rb - uninstall.rb

30 Plugin Hooks: Install.rb Auto-run when plugin is installed via script/plugin install Potential Uses Display README Copy needed images, styles, scripts Remove them with uninstall.rb

31 Plugin Hooks: Init.rb Runs whenever your application is started Use it to inject plugin code into the framework Add class methods in IsbnValidation module to AR::Base ActiveRecord::Base.class_eval do ext IsbnValidation

32 Adding Instance Methods? Use include instead of ext self.included class method is special Executed when the module is mixed in with include Gives us access to the including class Common Ruby idiom allows us to ext the base class with a new set of class methods here, too def self.included(base) base.ext(classmethods)

33 Should I Test My Plugin? If you re extracting a plugin, you probably already have tests for a lot of that functionality, right?

34 Testing Strategies Varies deping on the type of plugin Mock/stub out your environment if possible Test the behavior of the system with plugin installed Rather than the eccentricities of the plugin code itself For model plugins, consider creating an isolated in-memory database (sqlite3) Rake testing tasks already provided See Rakefile and sample test provided by generator rake test:plugins

35 Test Helper $:.unshift(file.dirname( FILE ) + '/../lib') RAILS_ROOT = File.dirname( FILE ) require 'rubygems' require 'test/unit' require 'active_record' require "#{File.dirname( FILE )}/../init" config = YAML::load(IO.read( File.dirname( FILE ) + '/database.yml')) ActiveRecord::Base.logger = Logger.new( File.dirname( FILE ) + "/debug.log") ActiveRecord::Base.establish_connection( config[env['db'] 'sqlite3']) load(file.dirname( FILE ) + "/schema.rb") if File.exist?( File.dirname( FILE ) + "/schema.rb")

36 Dummy Test Models (models.rb) class Book < ActiveRecord::Base validates_isbn :isbn, :message => 'is too fantastical!' class Book10 < ActiveRecord::Base set_table_name 'books' validates_isbn :isbn, :with => :isbn10 class Book13 < ActiveRecord::Base set_table_name 'books' validates_isbn :isbn, :with => :isbn13

37 Unit Testing require File.dirname( FILE ) + '/test_helper' require File.dirname( FILE ) + '/models' class IsbnValidationTest < Test::Unit::TestCase def = Book.new def = ' ' #...

38 Rspec fan? Use Pat Maddox s RSpec plugin generator Uses RSpec stubs instead of Test::Unit Also sets up isolated database for you! --with-database Install the plugin ruby script/generate rspec_plugin isbn_validation

39 Distributing Plugins Use a publicly visible Subversion or Git repository. It s that easy. Options: Google Code (Subversion) RubyForge (Subversion) GitHub (Git) <= Recommed!

40 ruby script/plugin install \ git://github.com/zapnap/isbn_validation.git

41 Distributing Plugins as Gems? Can also package plugins as RubyGems In environment.rb: config.gem isbn_validation, :source => gems.github.com, :version => >= Then, to install it in the project: rake gems:install rake gems:unpack rake gems:unpack:depencies

42 Gem Advantages Reasons to prefer Gems for packaging Proper versioning Depency management GitHub makes Gem creation easy Gems will be automatically created for you Installable via gems.github.com

43 Gemify! GitHub workflow Create a rails/init.rb file in your repository Change original init.rb to include only: require File.dirname( FILE ) + /rails/init.rb Create a Gemspec in the root of your repository Rake task to generate a Gemspec! Check RubyGem box on GitHub project edit page Can now install as either a RubyGem or a Plugin!

44 spec = Gem::Specification.new do s s.name = %q{isbn_validation} s.version = "0.1.0" s.summary = %q{adds an isbn validation...} s.description = %q{adds an isbn validation...} s.files = FileList['[A-Z]*', '{lib,test}/**/*.rb'] s.require_path = 'lib' s.test_files = Dir[*['test/**/*_test.rb']] s.authors = ["Nick Plante"] s. = %q{nap@zerosum.org} s.platform = Gem::Platform::RUBY s.add_depency(%q<activerecord>, [">= 2.1.2"]) desc "Generate a gemspec file" task :gemspec do File.open("#{spec.name}.gemspec", 'w') do f f.write spec.to_ruby

45 What Else? Rake tasks Put them in plugin tasks directory Note: this does not work for GemPlugins yet Namespace them appropriately namespace :isbn do Automatically made available in the host Rails project s list of Rake tasks Test and rdoc tasks are free

46 PDI Every plugin will require different strategies for development & testing Model, Controller, View Plugins Plugins that generate code Plugins that wrap third party daemons & libraries Fortunately, lots of OSS plugins to look to for examples -- no better way to learn! Good luck & don t forget to let us know about your new plugin!

47 Thanks! Nick Partner, Software Developer Ubikorp Internet Services