From e08af7219795d28fe9e9eb5f0dc2e7488541382e Mon Sep 17 00:00:00 2001 From: Jeff Dean Date: Sun, 16 Nov 2008 23:09:12 -0500 Subject: Rails guide: Misc reorganization --- railties/doc/guides/html/creating_plugins.html | 84 ++++++++++------------ .../guides/source/creating_plugins/core_ext.txt | 27 +------ .../source/creating_plugins/generator_commands.txt | 1 + .../guides/source/creating_plugins/migrations.txt | 2 + .../doc/guides/source/creating_plugins/setup.txt | 22 +++++- .../doc/guides/source/creating_plugins/tests.txt | 6 +- 6 files changed, 65 insertions(+), 77 deletions(-) (limited to 'railties/doc') diff --git a/railties/doc/guides/html/creating_plugins.html b/railties/doc/guides/html/creating_plugins.html index 1762bd95d2..8f32f72458 100644 --- a/railties/doc/guides/html/creating_plugins.html +++ b/railties/doc/guides/html/creating_plugins.html @@ -206,12 +206,16 @@ ul#navMain {
  • Generate the plugin skeleton
    • +
  • Organize your files
    • +
  • Tests @@ -220,10 +224,6 @@ ul#navMain { Extending core classes @@ -452,12 +452,30 @@ create vendor/plugins/yaffle/generators/yaffle/templates create vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb create vendor/plugins/yaffle/generators/yaffle/USAGE -

    To begin just change one thing - move init.rb to rails/init.rb.

    +

    1.3. 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:

    +
    +
    +
    |-- lib
+|   |-- yaffle
+|   `-- yaffle.rb
+`-- rails
+    |
+    `-- init.rb
    +
    +

    vendor/plugins/yaffle/rails/init.rb

    +
    +
    +
    require 'yaffle'
+
    +

    Now you can add any require statements to lib/yaffle.rb and keep init.rb clean.

    2. Tests

    -

    If your plugin interacts with a database, you'll need to setup a database connection. In this guide you will learn how to test your plugin against multiple different database adapters using Active Record. This guide will not cover how to use fixtures in plugin tests.

    -

    To setup your plugin to allow for easy testing you'll need to add 3 files:

    +

    In this guide you will learn how to test your plugin against multiple different database adapters using Active Record. To setup your plugin to allow for easy testing you'll need to add 3 files:

    • @@ -475,6 +493,7 @@ A test helper method that sets up the database

    +

    2.1. Test Setup

    vendor/plugins/yaffle/test/database.yml:

    @@ -565,7 +584,7 @@ ENV['RAILS_ROOT end

    Now whenever you write a test that requires the database, you can call load_schema.

    -

    2.1. Run the plugin tests

    +

    2.2. 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:

    vendor/plugins/yaffle/test/yaffle_test.rb:

    @@ -628,20 +647,7 @@ rake DB=postgresql

    3. Extending core classes

    -

    This section will explain how to add a method to String that will be available anywhere in your rails app by:

    -
      -
    • -

      -Writing tests for the desired behavior -

      -
      • -
    • -

      -Creating and requiring the correct files -

      -
      • -
    -

    3.1. Creating the test

    +

    This section will explain how to add a method to String that will be available anywhere in your rails app.

    In this example you will add a method to String named to_squawk. To begin, create a new test file with a few assertions:

    vendor/plugins/yaffle/test/core_ext_test.rb

    @@ -672,24 +678,6 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String ./test/core_ext_test.rb:5:in `test_to_squawk_prepends_the_word_squawk'

    Great - now you are ready to start development.

    -

    3.2. Organize your files

    -

    A common pattern in rails plugins is to set up the file structure like this:

    -
    -
    -
    |-- lib
-|   |-- yaffle
-|   |   `-- core_ext.rb
-|   `-- yaffle.rb
    -
    -

    The first thing we need to to is to require our lib/yaffle.rb file from rails/init.rb:

    -

    vendor/plugins/yaffle/rails/init.rb

    -
    -
    -
    require 'yaffle'
-

    Then in lib/yaffle.rb require lib/core_ext.rb:

    vendor/plugins/yaffle/lib/yaffle.rb

    @@ -719,7 +707,7 @@ http://www.gnu.org/software/src-highlite --> >> "Hello World".to_squawk => "squawk! Hello World"
    -

    3.3. Working with init.rb

    +

    3.1. Working with init.rb

    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.

    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.

    If you must reopen a class in init.rb you can use module_eval or class_eval to avoid any issues:

    @@ -1471,7 +1459,8 @@ http://www.gnu.org/software/src-highlite --> Note -If you haven't set up the custom route from above, script/destroy will fail and you'll have to remove it manually. + +
    Editor's note:
    If you haven't set up the custom route from above, script/destroy will fail and you'll have to remove it manually. @@ -1569,7 +1558,8 @@ http://www.gnu.org/software/src-highlite --> Note -several plugin frameworks such as Desert and Engines provide more advanced plugin functionality. + +
    Editor's note:
    several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.

    11.3. Generate migrations

    @@ -1639,7 +1629,8 @@ http://www.gnu.org/software/src-highlite --> Note -the migration generator checks to see if a migation already exists, and it's hard-coded to check the db/migrate directory. As a result, if your test tries to generate a migration that already exists in the app, it will fail. The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app. + +
    Editor's note:
    the migration generator checks to see if a migation already exists, and it's hard-coded to check the db/migrate directory. As a result, if your test tries to generate a migration that already exists in the app, it will fail. The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app.

    After running the test with rake you can make it pass with:

    @@ -1776,7 +1767,7 @@ sudo gem install pkg/yaffle-0.0.1.gem

    14. RDoc Documentation

    -

    Once your plugin is stable, the tests pass on all database and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy.

    +

    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.

    The first step is to update the README file with detailed information about how to use your plugin. A few key things to include are:

    • @@ -1800,8 +1791,7 @@ Warning, gotchas or tips that might help save users time

    -

    Once your README is solid, go through and add rdoc comments to all of the methods that developers will use.

    -

    Before you generate your documentation, be sure to go through and add nodoc comments to those modules and methods that are not important to your users.

    +

    Once your README is solid, go through and add rdoc comments to all of the methods that developers will use. It's also customary to add #:nodoc: comments to those parts of the code that are not part of the public api.

    Once your comments are good to go, navigate to your plugin directory and run:

    diff --git a/railties/doc/guides/source/creating_plugins/core_ext.txt b/railties/doc/guides/source/creating_plugins/core_ext.txt index ca8efc3df1..efef0e1f70 100644 --- a/railties/doc/guides/source/creating_plugins/core_ext.txt +++ b/railties/doc/guides/source/creating_plugins/core_ext.txt @@ -1,11 +1,6 @@ == Extending core classes == -This section will explain how to add a method to String that will be available anywhere in your rails app by: - - * Writing tests for the desired behavior - * Creating and requiring the correct files - -=== Creating the test === +This section will explain how to add a method to String that will be available anywhere in your rails app. In this example you will add a method to String named `to_squawk`. To begin, create a new test file with a few assertions: @@ -40,26 +35,6 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String Great - now you are ready to start development. -=== Organize your files === - -A common pattern in rails plugins is to set up the file structure like this: - --------------------------------------------------------- -|-- lib -| |-- yaffle -| | `-- core_ext.rb -| `-- yaffle.rb --------------------------------------------------------- - -The first thing we need to to is to require our 'lib/yaffle.rb' file from 'rails/init.rb': - -*vendor/plugins/yaffle/rails/init.rb* - -[source, ruby] --------------------------------------------------------- -require 'yaffle' --------------------------------------------------------- - Then in 'lib/yaffle.rb' require 'lib/core_ext.rb': *vendor/plugins/yaffle/lib/yaffle.rb* diff --git a/railties/doc/guides/source/creating_plugins/generator_commands.txt b/railties/doc/guides/source/creating_plugins/generator_commands.txt index 5cce81c8bd..3ace3c7318 100644 --- a/railties/doc/guides/source/creating_plugins/generator_commands.txt +++ b/railties/doc/guides/source/creating_plugins/generator_commands.txt @@ -137,4 +137,5 @@ To see this work, type: ./script/destroy yaffle_route ----------------------------------------------------------- +.Editor's note: NOTE: If you haven't set up the custom route from above, 'script/destroy' will fail and you'll have to remove it manually. \ No newline at end of file diff --git a/railties/doc/guides/source/creating_plugins/migrations.txt b/railties/doc/guides/source/creating_plugins/migrations.txt index 4dd932734d..d158004ea3 100644 --- a/railties/doc/guides/source/creating_plugins/migrations.txt +++ b/railties/doc/guides/source/creating_plugins/migrations.txt @@ -89,6 +89,7 @@ class CreateBirdhouses < ActiveRecord::Migration end ---------------------------------------------- +.Editor's note: NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality. === Generate migrations === @@ -146,6 +147,7 @@ class MigrationGeneratorTest < Test::Unit::TestCase end ------------------------------------------------------------------ +.Editor's note: NOTE: the migration generator checks to see if a migation already exists, and it's hard-coded to check the 'db/migrate' directory. As a result, if your test tries to generate a migration that already exists in the app, it will fail. The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app. After running the test with 'rake' you can make it pass with: diff --git a/railties/doc/guides/source/creating_plugins/setup.txt b/railties/doc/guides/source/creating_plugins/setup.txt index fcf5b459e6..cd4b6ecb04 100644 --- a/railties/doc/guides/source/creating_plugins/setup.txt +++ b/railties/doc/guides/source/creating_plugins/setup.txt @@ -61,4 +61,24 @@ create vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb create vendor/plugins/yaffle/generators/yaffle/USAGE ---------------------------------------------- -To begin just change one thing - move 'init.rb' to 'rails/init.rb'. +=== 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: + +-------------------------------------------------------- +|-- lib +| |-- yaffle +| `-- yaffle.rb +`-- rails + | + `-- init.rb +-------------------------------------------------------- + +*vendor/plugins/yaffle/rails/init.rb* + +[source, ruby] +-------------------------------------------------------- +require 'yaffle' +-------------------------------------------------------- + +Now you can add any 'require' statements to 'lib/yaffle.rb' and keep 'init.rb' clean. \ No newline at end of file diff --git a/railties/doc/guides/source/creating_plugins/tests.txt b/railties/doc/guides/source/creating_plugins/tests.txt index ef6dab2f9f..47611542cb 100644 --- a/railties/doc/guides/source/creating_plugins/tests.txt +++ b/railties/doc/guides/source/creating_plugins/tests.txt @@ -1,13 +1,13 @@ == Tests == -If your plugin interacts with a database, you'll need to setup a database connection. In this guide you will learn how to test your plugin against multiple different database adapters using Active Record. This guide will not cover how to use fixtures in plugin tests. - -To setup your plugin to allow for easy testing you'll need to add 3 files: +In this guide you will learn how to test your plugin against multiple different database adapters using Active Record. To setup your plugin to allow for easy testing you'll need to add 3 files: * A 'database.yml' file with all of your connection strings * A 'schema.rb' file with your table definitions * A test helper method that sets up the database +=== Test Setup === + *vendor/plugins/yaffle/test/database.yml:* ---------------------------------------------- -- cgit v1.2.3