railties 3.1.3 → 3.1.4.rc1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (180) hide show
  1. data/CHANGELOG.md +17 -2
  2. data/guides/source/3_1_release_notes.textile +107 -0
  3. data/guides/source/active_record_querying.textile +1 -1
  4. data/guides/source/asset_pipeline.textile +3 -11
  5. data/guides/source/configuring.textile +3 -1
  6. data/guides/source/i18n.textile +1 -1
  7. data/guides/source/performance_testing.textile +1 -1
  8. data/guides/source/routing.textile +1 -1
  9. data/lib/rails/application.rb +21 -1
  10. data/lib/rails/application/configuration.rb +3 -1
  11. data/lib/rails/generators/app_base.rb +19 -5
  12. data/lib/rails/generators/rails/app/templates/config/environments/development.rb.tt +2 -0
  13. data/lib/rails/generators/rails/app/templates/config/environments/production.rb.tt +4 -0
  14. data/lib/rails/tasks/documentation.rake +1 -1
  15. data/lib/rails/version.rb +2 -2
  16. metadata +335 -491
  17. data/guides/output/2_2_release_notes.html +0 -565
  18. data/guides/output/2_3_release_notes.html +0 -713
  19. data/guides/output/3_0_release_notes.html +0 -652
  20. data/guides/output/3_1_release_notes.html +0 -670
  21. data/guides/output/action_controller_overview.html +0 -925
  22. data/guides/output/action_mailer_basics.html +0 -658
  23. data/guides/output/action_view_overview.html +0 -1471
  24. data/guides/output/active_model_basics.html +0 -349
  25. data/guides/output/active_record_basics.html +0 -364
  26. data/guides/output/active_record_querying.html +0 -1272
  27. data/guides/output/active_record_validations_callbacks.html +0 -1292
  28. data/guides/output/active_resource_basics.html +0 -252
  29. data/guides/output/active_support_core_extensions.html +0 -3374
  30. data/guides/output/ajax_on_rails.html +0 -412
  31. data/guides/output/api_documentation_guidelines.html +0 -317
  32. data/guides/output/asset_pipeline.html +0 -691
  33. data/guides/output/association_basics.html +0 -1742
  34. data/guides/output/caching_with_rails.html +0 -533
  35. data/guides/output/command_line.html +0 -662
  36. data/guides/output/configuring.html +0 -811
  37. data/guides/output/contribute.html +0 -216
  38. data/guides/output/contributing_to_ruby_on_rails.html +0 -465
  39. data/guides/output/credits.html +0 -210
  40. data/guides/output/debugging_rails_applications.html +0 -791
  41. data/guides/output/engines.html +0 -673
  42. data/guides/output/form_helpers.html +0 -850
  43. data/guides/output/generators.html +0 -725
  44. data/guides/output/getting_started.html +0 -1980
  45. data/guides/output/i18n.html +0 -1054
  46. data/guides/output/images/belongs_to.png +0 -0
  47. data/guides/output/images/book_icon.gif +0 -0
  48. data/guides/output/images/bullet.gif +0 -0
  49. data/guides/output/images/challenge.png +0 -0
  50. data/guides/output/images/chapters_icon.gif +0 -0
  51. data/guides/output/images/check_bullet.gif +0 -0
  52. data/guides/output/images/credits_pic_blank.gif +0 -0
  53. data/guides/output/images/csrf.png +0 -0
  54. data/guides/output/images/customized_error_messages.png +0 -0
  55. data/guides/output/images/edge_badge.png +0 -0
  56. data/guides/output/images/error_messages.png +0 -0
  57. data/guides/output/images/feature_tile.gif +0 -0
  58. data/guides/output/images/footer_tile.gif +0 -0
  59. data/guides/output/images/fxn.png +0 -0
  60. data/guides/output/images/grey_bullet.gif +0 -0
  61. data/guides/output/images/habtm.png +0 -0
  62. data/guides/output/images/has_many.png +0 -0
  63. data/guides/output/images/has_many_through.png +0 -0
  64. data/guides/output/images/has_one.png +0 -0
  65. data/guides/output/images/has_one_through.png +0 -0
  66. data/guides/output/images/header_backdrop.png +0 -0
  67. data/guides/output/images/header_tile.gif +0 -0
  68. data/guides/output/images/i18n/demo_html_safe.png +0 -0
  69. data/guides/output/images/i18n/demo_localized_pirate.png +0 -0
  70. data/guides/output/images/i18n/demo_translated_en.png +0 -0
  71. data/guides/output/images/i18n/demo_translated_pirate.png +0 -0
  72. data/guides/output/images/i18n/demo_translation_missing.png +0 -0
  73. data/guides/output/images/i18n/demo_untranslated.png +0 -0
  74. data/guides/output/images/icons/README +0 -5
  75. data/guides/output/images/icons/callouts/1.png +0 -0
  76. data/guides/output/images/icons/callouts/10.png +0 -0
  77. data/guides/output/images/icons/callouts/11.png +0 -0
  78. data/guides/output/images/icons/callouts/12.png +0 -0
  79. data/guides/output/images/icons/callouts/13.png +0 -0
  80. data/guides/output/images/icons/callouts/14.png +0 -0
  81. data/guides/output/images/icons/callouts/15.png +0 -0
  82. data/guides/output/images/icons/callouts/2.png +0 -0
  83. data/guides/output/images/icons/callouts/3.png +0 -0
  84. data/guides/output/images/icons/callouts/4.png +0 -0
  85. data/guides/output/images/icons/callouts/5.png +0 -0
  86. data/guides/output/images/icons/callouts/6.png +0 -0
  87. data/guides/output/images/icons/callouts/7.png +0 -0
  88. data/guides/output/images/icons/callouts/8.png +0 -0
  89. data/guides/output/images/icons/callouts/9.png +0 -0
  90. data/guides/output/images/icons/caution.png +0 -0
  91. data/guides/output/images/icons/example.png +0 -0
  92. data/guides/output/images/icons/home.png +0 -0
  93. data/guides/output/images/icons/important.png +0 -0
  94. data/guides/output/images/icons/next.png +0 -0
  95. data/guides/output/images/icons/note.png +0 -0
  96. data/guides/output/images/icons/prev.png +0 -0
  97. data/guides/output/images/icons/tip.png +0 -0
  98. data/guides/output/images/icons/up.png +0 -0
  99. data/guides/output/images/icons/warning.png +0 -0
  100. data/guides/output/images/jaimeiniesta.jpg +0 -0
  101. data/guides/output/images/nav_arrow.gif +0 -0
  102. data/guides/output/images/polymorphic.png +0 -0
  103. data/guides/output/images/posts_index.png +0 -0
  104. data/guides/output/images/radar.png +0 -0
  105. data/guides/output/images/rails_guides_logo.gif +0 -0
  106. data/guides/output/images/rails_logo_remix.gif +0 -0
  107. data/guides/output/images/rails_welcome.png +0 -0
  108. data/guides/output/images/session_fixation.png +0 -0
  109. data/guides/output/images/tab_grey.gif +0 -0
  110. data/guides/output/images/tab_info.gif +0 -0
  111. data/guides/output/images/tab_note.gif +0 -0
  112. data/guides/output/images/tab_red.gif +0 -0
  113. data/guides/output/images/tab_yellow.gif +0 -0
  114. data/guides/output/images/tab_yellow.png +0 -0
  115. data/guides/output/images/validation_error_messages.png +0 -0
  116. data/guides/output/images/vijaydev.jpg +0 -0
  117. data/guides/output/index.html +0 -300
  118. data/guides/output/initialization.html +0 -1087
  119. data/guides/output/javascripts/guides.js +0 -7
  120. data/guides/output/javascripts/syntaxhighlighter/shBrushAS3.js +0 -59
  121. data/guides/output/javascripts/syntaxhighlighter/shBrushAppleScript.js +0 -75
  122. data/guides/output/javascripts/syntaxhighlighter/shBrushBash.js +0 -59
  123. data/guides/output/javascripts/syntaxhighlighter/shBrushCSharp.js +0 -65
  124. data/guides/output/javascripts/syntaxhighlighter/shBrushColdFusion.js +0 -100
  125. data/guides/output/javascripts/syntaxhighlighter/shBrushCpp.js +0 -97
  126. data/guides/output/javascripts/syntaxhighlighter/shBrushCss.js +0 -91
  127. data/guides/output/javascripts/syntaxhighlighter/shBrushDelphi.js +0 -55
  128. data/guides/output/javascripts/syntaxhighlighter/shBrushDiff.js +0 -41
  129. data/guides/output/javascripts/syntaxhighlighter/shBrushErlang.js +0 -52
  130. data/guides/output/javascripts/syntaxhighlighter/shBrushGroovy.js +0 -67
  131. data/guides/output/javascripts/syntaxhighlighter/shBrushJScript.js +0 -52
  132. data/guides/output/javascripts/syntaxhighlighter/shBrushJava.js +0 -57
  133. data/guides/output/javascripts/syntaxhighlighter/shBrushJavaFX.js +0 -58
  134. data/guides/output/javascripts/syntaxhighlighter/shBrushPerl.js +0 -72
  135. data/guides/output/javascripts/syntaxhighlighter/shBrushPhp.js +0 -88
  136. data/guides/output/javascripts/syntaxhighlighter/shBrushPlain.js +0 -33
  137. data/guides/output/javascripts/syntaxhighlighter/shBrushPowerShell.js +0 -74
  138. data/guides/output/javascripts/syntaxhighlighter/shBrushPython.js +0 -64
  139. data/guides/output/javascripts/syntaxhighlighter/shBrushRuby.js +0 -55
  140. data/guides/output/javascripts/syntaxhighlighter/shBrushSass.js +0 -94
  141. data/guides/output/javascripts/syntaxhighlighter/shBrushScala.js +0 -51
  142. data/guides/output/javascripts/syntaxhighlighter/shBrushSql.js +0 -66
  143. data/guides/output/javascripts/syntaxhighlighter/shBrushVb.js +0 -56
  144. data/guides/output/javascripts/syntaxhighlighter/shBrushXml.js +0 -69
  145. data/guides/output/javascripts/syntaxhighlighter/shCore.js +0 -17
  146. data/guides/output/layout.html +0 -312
  147. data/guides/output/layouts_and_rendering.html +0 -1257
  148. data/guides/output/migrations.html +0 -751
  149. data/guides/output/nested_model_forms.html +0 -350
  150. data/guides/output/performance_testing.html +0 -858
  151. data/guides/output/plugins.html +0 -590
  152. data/guides/output/rails_application_templates.html +0 -368
  153. data/guides/output/rails_on_rack.html +0 -408
  154. data/guides/output/routing.html +0 -1246
  155. data/guides/output/ruby_on_rails_guides_guidelines.html +0 -218
  156. data/guides/output/security.html +0 -968
  157. data/guides/output/stylesheets/fixes.css +0 -16
  158. data/guides/output/stylesheets/main.css +0 -445
  159. data/guides/output/stylesheets/print.css +0 -52
  160. data/guides/output/stylesheets/reset.css +0 -43
  161. data/guides/output/stylesheets/style.css +0 -13
  162. data/guides/output/stylesheets/syntaxhighlighter/shCore.css +0 -226
  163. data/guides/output/stylesheets/syntaxhighlighter/shCoreDefault.css +0 -328
  164. data/guides/output/stylesheets/syntaxhighlighter/shCoreDjango.css +0 -331
  165. data/guides/output/stylesheets/syntaxhighlighter/shCoreEclipse.css +0 -339
  166. data/guides/output/stylesheets/syntaxhighlighter/shCoreEmacs.css +0 -324
  167. data/guides/output/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +0 -328
  168. data/guides/output/stylesheets/syntaxhighlighter/shCoreMDUltra.css +0 -324
  169. data/guides/output/stylesheets/syntaxhighlighter/shCoreMidnight.css +0 -324
  170. data/guides/output/stylesheets/syntaxhighlighter/shCoreRDark.css +0 -324
  171. data/guides/output/stylesheets/syntaxhighlighter/shThemeDefault.css +0 -117
  172. data/guides/output/stylesheets/syntaxhighlighter/shThemeDjango.css +0 -120
  173. data/guides/output/stylesheets/syntaxhighlighter/shThemeEclipse.css +0 -128
  174. data/guides/output/stylesheets/syntaxhighlighter/shThemeEmacs.css +0 -113
  175. data/guides/output/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +0 -117
  176. data/guides/output/stylesheets/syntaxhighlighter/shThemeMDUltra.css +0 -113
  177. data/guides/output/stylesheets/syntaxhighlighter/shThemeMidnight.css +0 -113
  178. data/guides/output/stylesheets/syntaxhighlighter/shThemeRDark.css +0 -113
  179. data/guides/output/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +0 -116
  180. data/guides/output/testing.html +0 -1182
@@ -1,590 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
-
4
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
- <head>
6
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
7
-
8
- <title>Ruby on Rails Guides: The Basics of Creating Rails Plugins</title>
9
-
10
- <link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
11
- <link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
12
-
13
- <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" />
14
- <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" />
15
-
16
- <link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" />
17
- </head>
18
- <body class="guide">
19
- <div id="topNav">
20
- <div class="wrapper">
21
- <strong>More at <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
22
- <a href="http://rubyonrails.org/">Overview</a> |
23
- <a href="http://rubyonrails.org/download">Download</a> |
24
- <a href="http://rubyonrails.org/deploy">Deploy</a> |
25
- <a href="https://github.com/rails/rails">Code</a> |
26
- <a href="http://rubyonrails.org/screencasts">Screencasts</a> |
27
- <a href="http://rubyonrails.org/documentation">Documentation</a> |
28
- <a href="http://rubyonrails.org/ecosystem">Ecosystem</a> |
29
- <a href="http://rubyonrails.org/community">Community</a> |
30
- <a href="http://weblog.rubyonrails.org/">Blog</a>
31
- </div>
32
- </div>
33
- <div id="header">
34
- <div class="wrapper clearfix">
35
- <h1><a href="index.html" title="Return to home page">Guides.rubyonrails.org</a></h1>
36
- <p class="hide"><a href="#mainCol">Skip navigation</a>.</p>
37
- <ul class="nav">
38
- <li><a href="index.html">Home</a></li>
39
- <li class="index"><a href="index.html" onclick="guideMenu(); return false;" id="guidesMenu">Guides Index</a>
40
- <div id="guides" class="clearfix" style="display: none;">
41
- <hr />
42
- <dl class="L">
43
- <dt>Start Here</dt>
44
- <dd><a href="getting_started.html">Getting Started with Rails</a></dd>
45
- <dt>Models</dt>
46
- <dd><a href="migrations.html">Rails Database Migrations</a></dd>
47
- <dd><a href="active_record_validations_callbacks.html">Active Record Validations and Callbacks</a></dd>
48
- <dd><a href="association_basics.html">Active Record Associations</a></dd>
49
- <dd><a href="active_record_querying.html">Active Record Query Interface</a></dd>
50
- <dt>Views</dt>
51
- <dd><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></dd>
52
- <dd><a href="form_helpers.html">Action View Form Helpers</a></dd>
53
- <dt>Controllers</dt>
54
- <dd><a href="action_controller_overview.html">Action Controller Overview</a></dd>
55
- <dd><a href="routing.html">Rails Routing from the Outside In</a></dd>
56
- </dl>
57
- <dl class="R">
58
- <dt>Digging Deeper</dt>
59
- <dd><a href="active_support_core_extensions.html">Active Support Core Extensions</a></dd>
60
- <dd><a href="i18n.html">Rails Internationalization API</a></dd>
61
- <dd><a href="action_mailer_basics.html">Action Mailer Basics</a></dd>
62
- <dd><a href="testing.html">Testing Rails Applications</a></dd>
63
- <dd><a href="security.html">Securing Rails Applications</a></dd>
64
- <dd><a href="debugging_rails_applications.html">Debugging Rails Applications</a></dd>
65
- <dd><a href="performance_testing.html">Performance Testing Rails Applications</a></dd>
66
- <dd><a href="configuring.html">Configuring Rails Applications</a></dd>
67
- <dd><a href="command_line.html">Rails Command Line Tools and Rake Tasks</a></dd>
68
- <dd><a href="caching_with_rails.html">Caching with Rails</a></dd>
69
- <dd><a href="asset_pipeline.html">Asset Pipeline</a></dd>
70
-
71
- <dt>Extending Rails</dt>
72
- <dd><a href="plugins.html">The Basics of Creating Rails Plugins</a></dd>
73
- <dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
74
- <dd><a href="generators.html">Creating and Customizing Rails Generators</a></dd>
75
-
76
- <dt>Contributing to Ruby on Rails</dt>
77
- <dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd>
78
- <dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd>
79
- <dd><a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a></dd>
80
-
81
- <dt>Release Notes</dt>
82
- <dd><a href="3_1_release_notes.html">Ruby on Rails 3.1 Release Notes</a></dd>
83
- <dd><a href="3_0_release_notes.html">Ruby on Rails 3.0 Release Notes</a></dd>
84
- <dd><a href="2_3_release_notes.html">Ruby on Rails 2.3 Release Notes</a></dd>
85
- <dd><a href="2_2_release_notes.html">Ruby on Rails 2.2 Release Notes</a></dd>
86
- </dl>
87
- </div>
88
- </li>
89
- <li><a href="contributing_to_ruby_on_rails.html">Contribute</a></li>
90
- <li><a href="credits.html">Credits</a></li>
91
- </ul>
92
- </div>
93
- </div>
94
- <hr class="hide" />
95
-
96
- <div id="feature">
97
- <div class="wrapper">
98
- <h2>The Basics of Creating Rails Plugins</h2>
99
- <p>A Rails plugin is either an extension or a modification of the core framework. Plugins provide:</p>
100
- <ul>
101
- <li>a way for developers to share bleeding-edge ideas without hurting the stable code base</li>
102
- <li>a segmented architecture so that units of code can be fixed or updated on their own release schedule</li>
103
- <li>an outlet for the core developers so that they don’t have to include every cool new feature under the sun</li>
104
- </ul>
105
- <p>After reading this guide you should be familiar with:</p>
106
- <ul>
107
- <li>Creating a plugin from scratch</li>
108
- <li>Writing and running tests for the plugin</li>
109
- </ul>
110
- <p>This guide describes how to build a test-driven plugin that will:</p>
111
- <ul>
112
- <li>Extend core ruby classes like Hash and String</li>
113
- <li>Add methods to ActiveRecord::Base in the tradition of the &#8216;acts_as&#8217; plugins</li>
114
- <li>Give you information about where to put generators in your plugin.</li>
115
- </ul>
116
- <p>For the purpose of this guide pretend for a moment that you are an avid bird watcher.
117
- Your favorite bird is the Yaffle, and you want to create a plugin that allows other developers to share in the Yaffle
118
- goodness.</p>
119
-
120
- <div id="subCol">
121
- <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
122
- <ol class="chapters">
123
- <li><a href="#setup">Setup</a><ul><li><a href="#either-generate-a-vendored-plugin">Either generate a vendored plugin&#8230;</a></li> <li><a href="#or-generate-a-gemified-plugin">Or generate a gemified plugin.</a></li></ul></li><li><a href="#testing-your-newly-generated-plugin">Testing your newly generated plugin</a></li><li><a href="#extending-core-classes">Extending Core Classes</a></li><li><a href="#add-an-acts_as-method-to-active-record">Add an &#8220;acts_as&#8221; Method to Active Record</a><ul><li><a href="#add-a-class-method">Add a Class Method</a></li> <li><a href="#add-an-instance-method">Add an Instance Method</a></li></ul></li><li><a href="#generators">Generators</a></li><li><a href="#publishing-your-gem">Publishing your Gem</a></li><li><a href="#non-gem-plugins">Non-Gem Plugins</a></li><li><a href="#rdoc-documentation">RDoc Documentation</a><ul><li><a href="#references">References</a></li></ul></li></ol></div>
124
- </div>
125
- </div>
126
-
127
- <div id="container">
128
- <div class="wrapper">
129
- <div id="mainCol">
130
- <h3 id="setup">1 Setup</h3>
131
- <p>Before you continue, take a moment to decide if your new plugin will be potentially shared across different Rails applications.</p>
132
- <ul>
133
- <li>If your plugin is specific to your application, your new plugin will be a <em>vendored plugin</em>.</li>
134
- <li>If you think your plugin may be used across applications, build it as a <em>gemified plugin</em>.</li>
135
- </ul>
136
- <h4 id="either-generate-a-vendored-plugin">1.1 Either generate a vendored plugin&#8230;</h4>
137
- <p>Use the <tt>rails generate plugin</tt> command in your Rails root directory
138
- to create a new plugin that will live in the <tt>vendor/plugins</tt>
139
- directory. See usage and options by asking for help:</p>
140
- <div class="code_container">
141
- <pre class="brush: plain; gutter: false; toolbar: false">
142
- $ rails generate plugin --help
143
- </pre>
144
- </div>
145
- <h4 id="or-generate-a-gemified-plugin">1.2 Or generate a gemified plugin.</h4>
146
- <p>Writing your Rails plugin as a gem, rather than as a vendored plugin,
147
- lets you share your plugin across different rails applications using
148
- RubyGems and Bundler.</p>
149
- <p>Rails 3.1 ships with a <tt>rails plugin new</tt> command which creates a
150
- skeleton for developing any kind of Rails extension with the ability
151
- to run integration tests using a dummy Rails application. See usage
152
- and options by asking for help:</p>
153
- <div class="code_container">
154
- <pre class="brush: plain; gutter: false; toolbar: false">
155
- $ rails plugin --help
156
- </pre>
157
- </div>
158
- <h3 id="testing-your-newly-generated-plugin">2 Testing your newly generated plugin</h3>
159
- <p>You can navigate to the directory that contains the plugin, run the <tt>bundle install</tt> command
160
- and run the one generated test using the <tt>rake</tt> command.</p>
161
- <p>You should see:</p>
162
- <div class="code_container">
163
- <pre class="brush: plain; gutter: false; toolbar: false">
164
- 2 tests, 2 assertions, 0 failures, 0 errors, 0 skips
165
- </pre>
166
- </div>
167
- <p>This will tell you that everything got generated properly and you are ready to start adding functionality.</p>
168
- <h3 id="extending-core-classes">3 Extending Core Classes</h3>
169
- <p>This section will explain how to add a method to String that will be available anywhere in your rails application.</p>
170
- <p>In this example you will add a method to String named <tt>to_squawk</tt>. To begin, create a new test file with a few assertions:</p>
171
- <div class="code_container">
172
- <pre class="brush: ruby; gutter: false; toolbar: false">
173
- # yaffle/test/core_ext_test.rb
174
-
175
- require 'test_helper'
176
-
177
- class CoreExtTest &lt; Test::Unit::TestCase
178
- def test_to_squawk_prepends_the_word_squawk
179
- assert_equal &quot;squawk! Hello World&quot;, &quot;Hello World&quot;.to_squawk
180
- end
181
- end
182
- </pre>
183
- </div>
184
- <p>Run <tt>rake</tt> to run the test. This test should fail because we haven&#8217;t implemented the <tt>to_squawk</tt> method:</p>
185
- <div class="code_container">
186
- <pre class="brush: plain; gutter: false; toolbar: false">
187
- 1) Error:
188
- test_to_squawk_prepends_the_word_squawk(CoreExtTest):
189
- NoMethodError: undefined method `to_squawk' for &quot;Hello World&quot;:String
190
- test/core_ext_test.rb:5:in `test_to_squawk_prepends_the_word_squawk'
191
- </pre>
192
- </div>
193
- <p>Great &#8211; now you are ready to start development.</p>
194
- <p>Then in <tt>lib/yaffle.rb</tt> require <tt>lib/core_ext</tt>:</p>
195
- <div class="code_container">
196
- <pre class="brush: ruby; gutter: false; toolbar: false">
197
- # yaffle/lib/yaffle.rb
198
-
199
- require &quot;yaffle/core_ext&quot;
200
-
201
- module Yaffle
202
- end
203
- </pre>
204
- </div>
205
- <p>Finally, create the <tt>core_ext.rb</tt> file and add the <tt>to_squawk</tt> method:</p>
206
- <div class="code_container">
207
- <pre class="brush: ruby; gutter: false; toolbar: false">
208
- # yaffle/lib/yaffle/core_ext.rb
209
-
210
- String.class_eval do
211
- def to_squawk
212
- &quot;squawk! #{self}&quot;.strip
213
- end
214
- end
215
- </pre>
216
- </div>
217
- <p>To test that your method does what it says it does, run the unit tests with <tt>rake</tt> from your plugin directory.</p>
218
- <div class="code_container">
219
- <pre class="brush: plain; gutter: false; toolbar: false">
220
- 3 tests, 3 assertions, 0 failures, 0 errors, 0 skips
221
- </pre>
222
- </div>
223
- <p>To see this in action, change to the test/dummy directory, fire up a console and start squawking:</p>
224
- <div class="code_container">
225
- <pre class="brush: plain; gutter: false; toolbar: false">
226
- $ rails console
227
- &gt;&gt; &quot;Hello World&quot;.to_squawk
228
- =&gt; &quot;squawk! Hello World&quot;
229
- </pre>
230
- </div>
231
- <h3 id="add-an-acts_as-method-to-active-record">4 Add an &#8220;acts_as&#8221; Method to Active Record</h3>
232
- <p>A common pattern in plugins is to add a method called &#8216;acts_as_something&#8217; to models. In this case, you
233
- want to write a method called &#8216;acts_as_yaffle&#8217; that adds a &#8216;squawk&#8217; method to your Active Record models.</p>
234
- <p>To begin, set up your files so that you have:</p>
235
- <div class="code_container">
236
- <pre class="brush: ruby; gutter: false; toolbar: false">
237
- # yaffle/test/acts_as_yaffle_test.rb
238
-
239
- require 'test_helper'
240
-
241
- class ActsAsYaffleTest &lt; Test::Unit::TestCase
242
- end
243
- </pre>
244
- </div>
245
- <div class="code_container">
246
- <pre class="brush: ruby; gutter: false; toolbar: false">
247
- # yaffle/lib/yaffle.rb
248
-
249
- require &quot;yaffle/core_ext&quot;
250
- require 'yaffle/acts_as_yaffle'
251
-
252
- module Yaffle
253
- end
254
- </pre>
255
- </div>
256
- <div class="code_container">
257
- <pre class="brush: ruby; gutter: false; toolbar: false">
258
- # yaffle/lib/yaffle/acts_as_yaffle.rb
259
-
260
- module Yaffle
261
- module ActsAsYaffle
262
- # your code will go here
263
- end
264
- end
265
- </pre>
266
- </div>
267
- <h4 id="add-a-class-method">4.1 Add a Class Method</h4>
268
- <p>This plugin will expect that you&#8217;ve added a method to your model named &#8216;last_squawk&#8217;. However, the
269
- plugin users might have already defined a method on their model named &#8216;last_squawk&#8217; that they use
270
- for something else. This plugin will allow the name to be changed by adding a class method called &#8216;yaffle_text_field&#8217;.</p>
271
- <p>To start out, write a failing test that shows the behavior you&#8217;d like:</p>
272
- <div class="code_container">
273
- <pre class="brush: ruby; gutter: false; toolbar: false">
274
- # yaffle/test/acts_as_yaffle_test.rb
275
-
276
- require 'test_helper'
277
-
278
- class ActsAsYaffleTest &lt; Test::Unit::TestCase
279
-
280
- def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
281
- assert_equal &quot;last_squawk&quot;, Hickwall.yaffle_text_field
282
- end
283
-
284
- def test_a_wickwalls_yaffle_text_field_should_be_last_tweet
285
- assert_equal &quot;last_tweet&quot;, Wickwall.yaffle_text_field
286
- end
287
-
288
- end
289
- </pre>
290
- </div>
291
- <p>When you run <tt>rake</tt>, you should see the following:</p>
292
- <div class="code_container">
293
- <pre class="brush: plain; gutter: false; toolbar: false">
294
- 1) Error:
295
- test_a_hickwalls_yaffle_text_field_should_be_last_squawk(ActsAsYaffleTest):
296
- NameError: uninitialized constant ActsAsYaffleTest::Hickwall
297
- test/acts_as_yaffle_test.rb:6:in `test_a_hickwalls_yaffle_text_field_should_be_last_squawk'
298
-
299
- 2) Error:
300
- test_a_wickwalls_yaffle_text_field_should_be_last_tweet(ActsAsYaffleTest):
301
- NameError: uninitialized constant ActsAsYaffleTest::Wickwall
302
- test/acts_as_yaffle_test.rb:10:in `test_a_wickwalls_yaffle_text_field_should_be_last_tweet'
303
-
304
- 5 tests, 3 assertions, 0 failures, 2 errors, 0 skips
305
- </pre>
306
- </div>
307
- <p>This tells us that we don&#8217;t have the necessary models (Hickwall and Wickwall) that we are trying to test.
308
- We can easily generate these models in our &#8220;dummy&#8221; Rails application by running the following commands from the
309
- test/dummy directory:</p>
310
- <div class="code_container">
311
- <pre class="brush: plain; gutter: false; toolbar: false">
312
- $ cd test/dummy
313
- $ rails generate model Hickwall last_squawk:string
314
- $ rails generate model Wickwall last_squawk:string last_tweet:string
315
- </pre>
316
- </div>
317
- <p>Now you can create the necessary database tables in your testing database by navigating to your dummy app
318
- and migrating the database. First</p>
319
- <div class="code_container">
320
- <pre class="brush: plain; gutter: false; toolbar: false">
321
- $ cd test/dummy
322
- $ rake db:migrate
323
- $ rake db:test:prepare
324
- </pre>
325
- </div>
326
- <p>While you are here, change the Hickwall and Wickwall models so that they know that they are supposed to act
327
- like yaffles.</p>
328
- <div class="code_container">
329
- <pre class="brush: ruby; gutter: false; toolbar: false">
330
- # test/dummy/app/models/hickwall.rb
331
-
332
- class Hickwall &lt; ActiveRecord::Base
333
- acts_as_yaffle
334
- end
335
-
336
- # test/dummy/app/models/wickwall.rb
337
-
338
- class Wickwall &lt; ActiveRecord::Base
339
- acts_as_yaffle :yaffle_text_field =&gt; :last_tweet
340
- end
341
- </pre>
342
- </div>
343
- <p>We will also add code to define the acts_as_yaffle method.</p>
344
- <div class="code_container">
345
- <pre class="brush: ruby; gutter: false; toolbar: false">
346
- # yaffle/lib/yaffle/acts_as_yaffle.rb
347
- module Yaffle
348
- module ActsAsYaffle
349
- extend ActiveSupport::Concern
350
-
351
- included do
352
- end
353
-
354
- module ClassMethods
355
- def acts_as_yaffle(options = {})
356
- # your code will go here
357
- end
358
- end
359
- end
360
- end
361
-
362
- ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle
363
- </pre>
364
- </div>
365
- <p>You can then return to the root directory (<tt>cd ../..</tt>) of your plugin and rerun the tests using <tt>rake</tt>.</p>
366
- <div class="code_container">
367
- <pre class="brush: plain; gutter: false; toolbar: false">
368
- 1) Error:
369
- test_a_hickwalls_yaffle_text_field_should_be_last_squawk(ActsAsYaffleTest):
370
- NoMethodError: undefined method `yaffle_text_field' for #&lt;Class:0x000001016661b8&gt;
371
- /Users/xxx/.rvm/gems/ruby-1.9.2-p136@xxx/gems/activerecord-3.0.3/lib/active_record/base.rb:1008:in `method_missing'
372
- test/acts_as_yaffle_test.rb:5:in `test_a_hickwalls_yaffle_text_field_should_be_last_squawk'
373
-
374
- 2) Error:
375
- test_a_wickwalls_yaffle_text_field_should_be_last_tweet(ActsAsYaffleTest):
376
- NoMethodError: undefined method `yaffle_text_field' for #&lt;Class:0x00000101653748&gt;
377
- Users/xxx/.rvm/gems/ruby-1.9.2-p136@xxx/gems/activerecord-3.0.3/lib/active_record/base.rb:1008:in `method_missing'
378
- test/acts_as_yaffle_test.rb:9:in `test_a_wickwalls_yaffle_text_field_should_be_last_tweet'
379
-
380
- 5 tests, 3 assertions, 0 failures, 2 errors, 0 skips
381
- </pre>
382
- </div>
383
- <p>Getting closer&#8230; Now we will implement the code of the acts_as_yaffle method to make the tests pass.</p>
384
- <div class="code_container">
385
- <pre class="brush: ruby; gutter: false; toolbar: false">
386
- # yaffle/lib/yaffle/acts_as_yaffle.rb
387
-
388
- module Yaffle
389
- module ActsAsYaffle
390
- extend ActiveSupport::Concern
391
-
392
- included do
393
- end
394
-
395
- module ClassMethods
396
- def acts_as_yaffle(options = {})
397
- cattr_accessor :yaffle_text_field
398
- self.yaffle_text_field = (options[:yaffle_text_field] || :last_squawk).to_s
399
- end
400
- end
401
- end
402
- end
403
-
404
- ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle
405
- </pre>
406
- </div>
407
- <p>When you run <tt>rake</tt> you should see the tests all pass:</p>
408
- <div class="code_container">
409
- <pre class="brush: plain; gutter: false; toolbar: false">
410
- 5 tests, 5 assertions, 0 failures, 0 errors, 0 skips
411
- </pre>
412
- </div>
413
- <h4 id="add-an-instance-method">4.2 Add an Instance Method</h4>
414
- <p>This plugin will add a method named &#8216;squawk&#8217; to any Active Record object that calls &#8216;acts_as_yaffle&#8217;. The &#8216;squawk&#8217;
415
- method will simply set the value of one of the fields in the database.</p>
416
- <p>To start out, write a failing test that shows the behavior you&#8217;d like:</p>
417
- <div class="code_container">
418
- <pre class="brush: ruby; gutter: false; toolbar: false">
419
- # yaffle/test/acts_as_yaffle_test.rb
420
- require 'test_helper'
421
-
422
- class ActsAsYaffleTest &lt; Test::Unit::TestCase
423
-
424
- def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
425
- assert_equal &quot;last_squawk&quot;, Hickwall.yaffle_text_field
426
- end
427
-
428
- def test_a_wickwalls_yaffle_text_field_should_be_last_tweet
429
- assert_equal &quot;last_tweet&quot;, Wickwall.yaffle_text_field
430
- end
431
-
432
- def test_hickwalls_squawk_should_populate_last_squawk
433
- hickwall = Hickwall.new
434
- hickwall.squawk(&quot;Hello World&quot;)
435
- assert_equal &quot;squawk! Hello World&quot;, hickwall.last_squawk
436
- end
437
-
438
- def test_wickwalls_squawk_should_populate_last_tweet
439
- wickwall = Wickwall.new
440
- wickwall.squawk(&quot;Hello World&quot;)
441
- assert_equal &quot;squawk! Hello World&quot;, wickwall.last_tweet
442
- end
443
- end
444
- </pre>
445
- </div>
446
- <p>Run the test to make sure the last two tests fail with an error that contains &#8220;NoMethodError: undefined method `squawk&#8217;&#8221;,
447
- then update &#8216;acts_as_yaffle.rb&#8217; to look like this:</p>
448
- <div class="code_container">
449
- <pre class="brush: ruby; gutter: false; toolbar: false">
450
- # yaffle/lib/yaffle/acts_as_yaffle.rb
451
-
452
- module Yaffle
453
- module ActsAsYaffle
454
- extend ActiveSupport::Concern
455
-
456
- included do
457
- end
458
-
459
- module ClassMethods
460
- def acts_as_yaffle(options = {})
461
- cattr_accessor :yaffle_text_field
462
- self.yaffle_text_field = (options[:yaffle_text_field] || :last_squawk).to_s
463
- end
464
- end
465
-
466
- def squawk(string)
467
- write_attribute(self.class.yaffle_text_field, string.to_squawk)
468
- end
469
-
470
- end
471
- end
472
-
473
- ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle
474
- </pre>
475
- </div>
476
- <p>Run <tt>rake</tt> one final time and you should see:</p>
477
- <div class="code_container">
478
- <pre class="brush: plain; gutter: false; toolbar: false">
479
- 7 tests, 7 assertions, 0 failures, 0 errors, 0 skips
480
- </pre>
481
- </div>
482
- <div class="note"><p>The use of <tt>write_attribute</tt> to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use <tt>send(&#8220;#{self.class.yaffle_text_field}=&#8221;, string.to_squawk)</tt>.</p></div>
483
- <h3 id="generators">5 Generators</h3>
484
- <p>Generators can be included in your gem simply by creating them in a lib/generators directory of your plugin. More information about
485
- the creation of generators can be found in the <a href="generators.html">Generators Guide</a></p>
486
- <h3 id="publishing-your-gem">6 Publishing your Gem</h3>
487
- <p>Gem plugins currently in development can easily be shared from any Git repository. To share the Yaffle gem with others, simply
488
- commit the code to a Git repository (like Github) and add a line to the Gemfile of the application in question:</p>
489
- <div class="code_container">
490
- <pre class="brush: ruby; gutter: false; toolbar: false">
491
- gem 'yaffle', :git =&gt; 'git://github.com/yaffle_watcher/yaffle.git'
492
- </pre>
493
- </div>
494
- <p>After running <tt>bundle install</tt>, your gem functionality will be available to the application.</p>
495
- <p>When the gem is ready to be shared as a formal release, it can be published to <a href="http://www.rubygems.org">RubyGems</a>.
496
- For more information about publishing gems to RubyGems, see: <a href="http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html">http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html</a></p>
497
- <h3 id="non-gem-plugins">7 Non-Gem Plugins</h3>
498
- <p>Non-gem plugins are useful for functionality that won&#8217;t be shared with another project. Keeping your custom functionality in the
499
- vendor/plugins directory un-clutters the rest of the application.</p>
500
- <p>Move the directory that you created for the gem based plugin into the vendor/plugins directory of a generated Rails application, create a vendor/plugins/yaffle/init.rb file that contains &#8220;require &#8216;yaffle&#8217;&#8221; and everything will still work.</p>
501
- <div class="code_container">
502
- <pre class="brush: ruby; gutter: false; toolbar: false">
503
- # yaffle/init.rb
504
-
505
- require 'yaffle'
506
- </pre>
507
- </div>
508
- <p>You can test this by changing to the Rails application that you added the plugin to and starting a rails console. Once in the
509
- console we can check to see if the String has an instance method to_squawk:</p>
510
- <div class="code_container">
511
- <pre class="brush: plain; gutter: false; toolbar: false">
512
- $ cd my_app
513
- $ rails console
514
- $ &quot;Rails plugins are easy!&quot;.to_squawk
515
- </pre>
516
- </div>
517
- <p>You can also remove the .gemspec, Gemfile and Gemfile.lock files as they will no longer be needed.</p>
518
- <h3 id="rdoc-documentation">8 RDoc Documentation</h3>
519
- <p>Once your plugin is stable and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy.</p>
520
- <p>The first step is to update the <span class="caps">README</span> file with detailed information about how to use your plugin. A few key things to include are:</p>
521
- <ul>
522
- <li>Your name</li>
523
- <li>How to install</li>
524
- <li>How to add the functionality to the app (several examples of common use cases)</li>
525
- <li>Warnings, gotchas or tips that might help users and save them time</li>
526
- </ul>
527
- <p>Once your <span class="caps">README</span> is solid, go through and add rdoc comments to all of the methods that developers will use. It&#8217;s also customary to add &#8216;#:nodoc:&#8217; comments to those parts of the code that are not included in the public api.</p>
528
- <p>Once your comments are good to go, navigate to your plugin directory and run:</p>
529
- <div class="code_container">
530
- <pre class="brush: plain; gutter: false; toolbar: false">
531
- $ rake rdoc
532
- </pre>
533
- </div>
534
- <h4 id="references">8.1 References</h4>
535
- <ul>
536
- <li><a href="https://github.com/radar/guides/blob/master/gem-development.md">Developing a RubyGem using Bundler</a></li>
537
- <li><a href="http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/">Using Gemspecs As Intended</a></li>
538
- <li><a href="http://docs.rubygems.org/read/chapter/20">Gemspec Reference</a></li>
539
- <li><a href="http://www.mbleigh.com/2008/06/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins">GemPlugins</a></li>
540
- <li><a href="http://daddy.platte.name/2007/05/rails-plugins-keep-initrb-thin.html">Keeping init.rb thin</a></li>
541
- </ul>
542
-
543
- <h3>Feedback</h3>
544
- <p>
545
- You're encouraged to help improve the quality of this guide.
546
- </p>
547
- <p>
548
- If you see any typos or factual errors you are confident to
549
- patch, please clone <a href="https://github.com/lifo/docrails">docrails</a>
550
- and push the change yourself. That branch of Rails has public write access.
551
- Commits are still reviewed, but that happens after you've submitted your
552
- contribution. <a href="https://github.com/lifo/docrails">docrails</a> is
553
- cross-merged with master periodically.
554
- </p>
555
- <p>
556
- You may also find incomplete content, or stuff that is not up to date.
557
- Please do add any missing documentation for master. Check the
558
- <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a>
559
- for style and conventions.
560
- </p>
561
- <p>
562
- If for whatever reason you spot something to fix but cannot patch it yourself, please
563
- <a href="https://github.com/rails/rails/issues">open an issue</a>.
564
- </p>
565
- <p>And last but not least, any kind of discussion regarding Ruby on Rails
566
- documentation is very welcome in the <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs mailing list</a>.
567
- </p>
568
- </div>
569
- </div>
570
- </div>
571
-
572
- <hr class="hide" />
573
- <div id="footer">
574
- <div class="wrapper">
575
- <p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0</a> License</p>
576
- <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p>
577
- </div>
578
- </div>
579
-
580
- <script type="text/javascript" src="javascripts/guides.js"></script>
581
- <script type="text/javascript" src="javascripts/syntaxhighlighter/shCore.js"></script>
582
- <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
583
- <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
584
- <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
585
- <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
586
- <script type="text/javascript">
587
- SyntaxHighlighter.all()
588
- </script>
589
- </body>
590
- </html>