From 1c820dde75800cec158b0061a1890e8aa9cc91bd Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 14 Mar 2009 22:52:22 +0100 Subject: [PATCH] revised titles of plugins guide --- railties/guides/source/plugins.textile | 34 +++++++++++++------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index d2fb157e35..55ecdcd3d1 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -31,7 +31,7 @@ endprologue. h3. Setup -h4. Create the basic app +h4. Create the Basic Application The examples in this guide require that you have a working rails application. To create a simple rails app execute: @@ -49,7 +49,7 @@ Then navigate to http://localhost:3000/birds. Make sure you have a functioning NOTE: The aforementioned instructions will work for sqlite3. For more detailed instructions on how to create a rails app for other databases see the API docs. -h4. Generate the plugin skeleton +h4. Generate the Plugin Skeleton Rails ships with a plugin generator which creates a basic plugin skeleton. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass +--with-generator+ to add an example generator also. @@ -91,7 +91,7 @@ create vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb create vendor/plugins/yaffle/generators/yaffle/USAGE -h4. Organize your files +h4. Organize Your Files To make it easy to organize your files and to make the plugin more compatible with GemPlugins, start out by altering your file system to look like this: @@ -211,7 +211,7 @@ end Now whenever you write a test that requires the database, you can call 'load_schema'. -h4. Run the plugin tests +h4. Run the Plugin Tests Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in 'vendor/plugins/yaffle/test/yaffle_test.rb' with a sample test. Replace the contents of that file with: @@ -275,7 +275,7 @@ rake DB=postgresql Now you are ready to test-drive your plugin! -h3. Extending core classes +h3. Extending Core Classes This section will explain how to add a method to String that will be available anywhere in your rails app. @@ -339,7 +339,7 @@ $ ./script/console => "squawk! Hello World" -h4. Working with init.rb +h4. Working with +init.rb+ When rails loads plugins it looks for the file named 'init.rb' or 'rails/init.rb'. However, when the plugin is initialized, 'init.rb' is invoked via +eval+ (not +require+) so it has slightly different behavior. @@ -369,7 +369,7 @@ class ::Hash end -h3. Add an 'acts_as' method to Active Record +h3. Add an "acts_as" Method to Active Record A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your models. @@ -425,7 +425,7 @@ end With structure you can easily separate the methods that will be used for the class (like +Hickwall.some_method+) and the instance (like +@hickwell.some_method+). -h4. Add a class method +h4. Add a Class Method This plugin will expect that you've added a method to your model named 'last_squawk'. However, the plugin users might have already defined a method on their model named 'last_squawk' that they use for something else. This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'. @@ -478,7 +478,7 @@ end ActiveRecord::Base.send :include, Yaffle -h4. Add an instance method +h4. Add an Instance Method This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'. The 'squawk' method will simply set the value of one of the fields in the database. @@ -800,7 +800,7 @@ Many plugins ship with generators. When you created the plugin above, you speci Building generators is a complex topic unto itself and this section will cover one small aspect of generators: generating a simple text file. -h4. Testing generators +h4. Testing Generators Many rails plugin authors do not test their generators, however testing generators is quite simple. A typical generator test does the following: @@ -864,7 +864,7 @@ class YaffleDefinitionGenerator < Rails::Generator::Base end -h4. The USAGE file +h4. The +USAGE+ File If you plan to distribute your plugin, developers will expect at least a minimum of documentation. You can add simple documentation to the generator by updating the USAGE file. @@ -891,7 +891,7 @@ Description: Adds a file with the definition of a Yaffle to the app's main directory -h3. Add a custom generator command +h3. Add a Custom Generator Command You may have noticed above that you can used one of the built-in rails migration commands +migration_template+. If your plugin needs to add and remove lines of text from existing files you will need to write your own generator methods. @@ -1144,7 +1144,7 @@ end Here are a few possibilities for how to allow developers to use your plugin migrations: -h4. Create a custom rake task +h4. Create a Custom Rake Task * *vendor/plugins/yaffle/tasks/yaffle_tasks.rake:* @@ -1165,7 +1165,7 @@ namespace :db do end -h4. Call migrations directly +h4. Call Migrations Directly * *vendor/plugins/yaffle/lib/yaffle.rb:* @@ -1191,7 +1191,7 @@ end NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality. -h4. Generate migrations +h4. Generate Migrations Generating migrations has several advantages over other methods. Namely, you can allow other developers to more easily customize the migration. The flow looks like this: @@ -1417,7 +1417,7 @@ h4. References * http://www.mbleigh.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins * http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2. -h4. Contents of 'lib/yaffle.rb' +h4. Contents of +lib/yaffle.rb+ * *vendor/plugins/yaffle/lib/yaffle.rb:* @@ -1440,7 +1440,7 @@ end # end -h4. Final plugin directory structure +h4. Final Plugin Directory Structure The final plugin should have a directory structure that looks something like this: