1 == Extending core classes ==
3 This section will explain how to add a method to String that will be available anywhere in your rails app by:
5 * Writing tests for the desired behavior
6 * Creating and requiring the correct files
8 === Creating the test ===
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:
12 *vendor/plugins/yaffle/test/core_ext_test.rb*
15 --------------------------------------------------------
16 require File.dirname(__FILE__) + '/test_helper.rb'
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
23 --------------------------------------------------------
25 Navigate to your plugin directory and run `rake test`:
27 --------------------------------------------------------
28 cd vendor/plugins/yaffle
30 --------------------------------------------------------
32 The test above should fail with the message:
34 --------------------------------------------------------
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 --------------------------------------------------------
41 Great - now you are ready to start development.
43 === Organize your files ===
45 A common pattern in rails plugins is to set up the file structure like this:
47 --------------------------------------------------------
52 --------------------------------------------------------
54 The first thing we need to to is to require our 'lib/yaffle.rb' file from 'rails/init.rb':
56 *vendor/plugins/yaffle/rails/init.rb*
59 --------------------------------------------------------
61 --------------------------------------------------------
63 Then in 'lib/yaffle.rb' require 'lib/core_ext.rb':
65 *vendor/plugins/yaffle/lib/yaffle.rb*
68 --------------------------------------------------------
69 require "yaffle/core_ext"
70 --------------------------------------------------------
72 Finally, create the 'core_ext.rb' file and add the 'to_squawk' method:
74 *vendor/plugins/yaffle/lib/yaffle/core_ext.rb*
77 --------------------------------------------------------
80 "squawk! #{self}".strip
83 --------------------------------------------------------
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:
87 --------------------------------------------------------
89 >> "Hello World".to_squawk
90 => "squawk! Hello World"
91 --------------------------------------------------------
93 === Working with init.rb ===
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.
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.
99 If you must reopen a class in `init.rb` you can use `module_eval` or `class_eval` to avoid any issues:
101 *vendor/plugins/yaffle/init.rb*
104 ---------------------------------------------------
106 def is_a_special_hash?
110 ---------------------------------------------------
112 Another way is to explicitly define the top-level module space for all modules and classes, like `::Hash`:
114 *vendor/plugins/yaffle/init.rb*
117 ---------------------------------------------------
119 def is_a_special_hash?
123 ---------------------------------------------------