vendor/rails/railties/doc/guides/source/creating_plugins/core_ext.txt

   1 == Extending core classes ==
   2
   3 This section will explain how to add a method to String that will be available anywhere in your rails app by:
   4
   5  * Writing tests for the desired behavior
   6  * Creating and requiring the correct files
   7
   8 === Creating the test ===
   9
  10 In this example you will add a method to String named `to_squawk`.  To begin, create a new test file with a few assertions:
  11
  12 *vendor/plugins/yaffle/test/core_ext_test.rb*
  13
  14 [source, ruby]
  15 --------------------------------------------------------
  16 require File.dirname(__FILE__) + '/test_helper.rb'
  17
  18 class CoreExtTest < Test::Unit::TestCase
  19   def test_to_squawk_prepends_the_word_squawk
  20     assert_equal "squawk! Hello World", "Hello World".to_squawk
  21   end
  22 end
  23 --------------------------------------------------------
  24
  25 Navigate to your plugin directory and run `rake test`:
  26
  27 --------------------------------------------------------
  28 cd vendor/plugins/yaffle
  29 rake test
  30 --------------------------------------------------------
  31
  32 The test above should fail with the message:
  33
  34 --------------------------------------------------------
  35  1) Error:
  36 test_to_squawk_prepends_the_word_squawk(CoreExtTest):
  37 NoMethodError: undefined method `to_squawk' for "Hello World":String
  38     ./test/core_ext_test.rb:5:in `test_to_squawk_prepends_the_word_squawk'
  39 --------------------------------------------------------
  40
  41 Great - now you are ready to start development.
  42
  43 === Organize your files ===
  44
  45 A common pattern in rails plugins is to set up the file structure like this:
  46
  47 --------------------------------------------------------
  48 |-- lib
  49 |   |-- yaffle
  50 |   |   `-- core_ext.rb
  51 |   `-- yaffle.rb
  52 --------------------------------------------------------
  53
  54 The first thing we need to to is to require our 'lib/yaffle.rb' file from 'rails/init.rb':
  55
  56 *vendor/plugins/yaffle/rails/init.rb*
  57
  58 [source, ruby]
  59 --------------------------------------------------------
  60 require 'yaffle'
  61 --------------------------------------------------------
  62
  63 Then in 'lib/yaffle.rb' require 'lib/core_ext.rb':
  64
  65 *vendor/plugins/yaffle/lib/yaffle.rb*
  66
  67 [source, ruby]
  68 --------------------------------------------------------
  69 require "yaffle/core_ext"
  70 --------------------------------------------------------
  71
  72 Finally, create the 'core_ext.rb' file and add the 'to_squawk' method:
  73
  74 *vendor/plugins/yaffle/lib/yaffle/core_ext.rb*
  75
  76 [source, ruby]
  77 --------------------------------------------------------
  78 String.class_eval do
  79   def to_squawk
  80     "squawk! #{self}".strip
  81   end
  82 end
  83 --------------------------------------------------------
  84
  85 To test that your method does what it says it does, run the unit tests with `rake` from your plugin directory.  To see this in action, fire up a console and start squawking:
  86
  87 --------------------------------------------------------
  88 $ ./script/console
  89 >> "Hello World".to_squawk
  90 => "squawk! Hello World"
  91 --------------------------------------------------------
  92
  93 === Working with init.rb ===
  94
  95 When rails loads plugins it looks for the file named init.rb.  However, when the plugin is initialized, 'init.rb' is invoked via `eval` (not `require`) so it has slightly different behavior.
  96
  97 Under certain circumstances if you reopen classes or modules in 'init.rb' you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from `init.rb`, as shown above.
  98
  99 If you must reopen a class in `init.rb` you can use `module_eval` or `class_eval` to avoid any issues:
 100
 101 *vendor/plugins/yaffle/init.rb*
 102
 103 [source, ruby]
 104 ---------------------------------------------------
 105 Hash.class_eval do
 106   def is_a_special_hash?
 107     true
 108   end
 109 end
 110 ---------------------------------------------------
 111
 112 Another way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
 113
 114 *vendor/plugins/yaffle/init.rb*
 115
 116 [source, ruby]
 117 ---------------------------------------------------
 118 class ::Hash
 119   def is_a_special_hash?
 120     true
 121   end
 122 end
 123 ---------------------------------------------------