From 40bc386ed8cc403050292ab19428f1e467fa1737 Mon Sep 17 00:00:00 2001 From: Jeff Dean Date: Wed, 12 Nov 2008 02:05:19 -0500 Subject: Plugin Guide: cleaned up file paths, made formatting more consistent --- .../source/creating_plugins/acts_as_yaffle.txt | 29 ++++++++++++---------- .../source/creating_plugins/custom_generator.txt | 14 +++++------ .../source/creating_plugins/custom_route.txt | 16 ++++++------ .../creating_plugins/migration_generator.txt | 20 +++++++++------ .../source/creating_plugins/odds_and_ends.txt | 4 +-- .../source/creating_plugins/string_to_squawk.txt | 21 ++++++++-------- .../guides/source/creating_plugins/view_helper.txt | 12 ++++----- 7 files changed, 62 insertions(+), 54 deletions(-) (limited to 'railties/doc/guides/source/creating_plugins') diff --git a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt index 12d40deb18..06878543e4 100644 --- a/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt +++ b/railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt @@ -4,10 +4,10 @@ A common pattern in plugins is to add a method called `acts_as_something` to mod To keep things clean, create a new test file called 'acts_as_yaffle_test.rb' in your plugin's test directory and require your test helper. +*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb - require File.dirname(__FILE__) + '/test_helper.rb' class Hickwall < ActiveRecord::Base @@ -18,16 +18,18 @@ class ActsAsYaffleTest < Test::Unit::TestCase end ------------------------------------------------------ +*vendor/plugins/lib/acts_as_yaffle.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/lib/acts_as_yaffle.rb - module Yaffle end ------------------------------------------------------ One of the most common plugin patterns for `acts_as_yaffle` plugins is to structure your file like so: +*vendor/plugins/lib/acts_as_yaffle.rb* + [source, ruby] ------------------------------------------------------ module Yaffle @@ -65,10 +67,10 @@ end Now that test should pass. Since your plugin is going to work with field names, you need to allow people to define the field names, in case there is a naming conflict. You can write a few simple tests for this: +*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb - require File.dirname(__FILE__) + '/test_helper.rb' class ActsAsYaffleTest < Test::Unit::TestCase @@ -92,10 +94,10 @@ end To make these tests pass, you could modify your `acts_as_yaffle` file like so: +*vendor/plugins/yaffle/lib/acts_as_yaffle.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/yaffle/lib/acts_as_yaffle.rb - module Yaffle def self.included(base) base.send :extend, ClassMethods @@ -117,10 +119,10 @@ end Now you can add tests for the instance methods, and the instance method itself: +*vendor/plugins/yaffle/test/acts_as_yaffle_test.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/yaffle/test/acts_as_yaffle_test.rb - require File.dirname(__FILE__) + '/test_helper.rb' class ActsAsYaffleTest < Test::Unit::TestCase @@ -163,10 +165,10 @@ class ActsAsYaffleTest < Test::Unit::TestCase end ------------------------------------------------------ +*vendor/plugins/yaffle/lib/acts_as_yaffle.rb* + [source, ruby] ------------------------------------------------------ -# File: vendor/plugins/yaffle/lib/acts_as_yaffle.rb - module Yaffle def self.included(base) base.send :extend, ClassMethods @@ -190,4 +192,5 @@ module Yaffle end ------------------------------------------------------ -Note the use of `write_attribute` to write to the field in model. +.Editor's note: +NOTE: The use of `write_attribute` 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 `send("#{self.class.yaffle_text_field}=", string.to_squawk)`. diff --git a/railties/doc/guides/source/creating_plugins/custom_generator.txt b/railties/doc/guides/source/creating_plugins/custom_generator.txt index 6d9613ea01..a8cf1b48ce 100644 --- a/railties/doc/guides/source/creating_plugins/custom_generator.txt +++ b/railties/doc/guides/source/creating_plugins/custom_generator.txt @@ -8,19 +8,20 @@ You may have noticed above that you can used one of the built-in rails migration Working with the internals of generators is beyond the scope of this tutorial, but here is a basic example: +*vendor/plugins/yaffle/init.rb* + [source, ruby] ----------------------------------------------------------- -# File: vendor/plugins/yaffle/init.rb require "commands" Rails::Generator::Commands::Create.send :include, Yaffle::Generator::Commands::Create Rails::Generator::Commands::Destroy.send :include, Yaffle::Generator::Commands::Destroy Rails::Generator::Commands::List.send :include, Yaffle::Generator::Commands::List ----------------------------------------------------------- +*vendor/plugins/yaffle/lib/commands.rb* + [source, ruby] ----------------------------------------------------------- -# File: vendor/plugins/yaffle/lib/commands.rb - require 'rails_generator' require 'rails_generator/commands' @@ -49,16 +50,15 @@ module Yaffle #:nodoc: end ----------------------------------------------------------- +*vendor/plugins/yaffle/generators/yaffle/templates/definition.txt* ----------------------------------------------------------- -# File: vendor/plugins/yaffle/generators/yaffle/templates/definition.txt - Yaffle is a bird ----------------------------------------------------------- +*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb* + [source, ruby] ----------------------------------------------------------- -# File: vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb - class YaffleGenerator < Rails::Generator::NamedBase def manifest m.yaffle_definition diff --git a/railties/doc/guides/source/creating_plugins/custom_route.txt b/railties/doc/guides/source/creating_plugins/custom_route.txt index 7e399247ee..1fce902a4e 100644 --- a/railties/doc/guides/source/creating_plugins/custom_route.txt +++ b/railties/doc/guides/source/creating_plugins/custom_route.txt @@ -2,10 +2,10 @@ Testing routes in plugins can be complex, especially if the controllers are also in the plugin itself. Jamis Buck showed a great example of this in http://weblog.jamisbuck.org/2006/10/26/monkey-patching-rails-extending-routes-2. +*vendor/plugins/yaffle/test/routing_test.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/test/routing_test.rb - require "#{File.dirname(__FILE__)}/test_helper" class RoutingTest < Test::Unit::TestCase @@ -33,18 +33,18 @@ class RoutingTest < Test::Unit::TestCase end -------------------------------------------------------- +*vendor/plugins/yaffle/init.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/init.rb - require "routing" ActionController::Routing::RouteSet::Mapper.send :include, Yaffle::Routing::MapperExtensions -------------------------------------------------------- +*vendor/plugins/yaffle/lib/routing.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/lib/routing.rb - module Yaffle #:nodoc: module Routing #:nodoc: module MapperExtensions @@ -56,10 +56,10 @@ module Yaffle #:nodoc: end -------------------------------------------------------- +*config/routes.rb* + [source, ruby] -------------------------------------------------------- -# File: config/routes.rb - ActionController::Routing::Routes.draw do |map| ... map.yaffles diff --git a/railties/doc/guides/source/creating_plugins/migration_generator.txt b/railties/doc/guides/source/creating_plugins/migration_generator.txt index 598a0c8437..1a477a69ab 100644 --- a/railties/doc/guides/source/creating_plugins/migration_generator.txt +++ b/railties/doc/guides/source/creating_plugins/migration_generator.txt @@ -6,11 +6,15 @@ We'll be relying on the built-in rails generate template for this tutorial. Goi Type: - script/generate +------------------------------------------------------------------ +script/generate +------------------------------------------------------------------ You should see the line: - Plugins (vendor/plugins): yaffle +------------------------------------------------------------------ +Plugins (vendor/plugins): yaffle +------------------------------------------------------------------ When you run `script/generate yaffle` you should see the contents of your USAGE file. For this plugin, the USAGE file looks like this: @@ -27,10 +31,10 @@ Example: Now you can add code to your generator: +*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb* + [source, ruby] ------------------------------------------------------------------ -# File: vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb - class YaffleGenerator < Rails::Generator::NamedBase def manifest record do |m| @@ -67,14 +71,16 @@ This does a few things: When you run the generator like - script/generate yaffle bird +------------------------------------------------------------------ +script/generate yaffle bird +------------------------------------------------------------------ You will see a new file: +*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb* + [source, ruby] ------------------------------------------------------------------ -# File: db/migrate/20080529225649_add_yaffle_fields_to_birds.rb - class AddYaffleFieldsToBirds < ActiveRecord::Migration def self.up add_column :birds, :last_squawk, :string diff --git a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt index 32da7ed7f3..88cd4fe9ed 100644 --- a/railties/doc/guides/source/creating_plugins/odds_and_ends.txt +++ b/railties/doc/guides/source/creating_plugins/odds_and_ends.txt @@ -81,10 +81,10 @@ When you created the plugin with the built-in rails generator, it generated a ra Many plugin authors put all of their rake tasks into a common namespace that is the same as the plugin, like so: +*vendor/plugins/yaffle/tasks/yaffle.rake* + [source, ruby] --------------------------------------------------------- -# File: vendor/plugins/yaffle/tasks/yaffle.rake - namespace :yaffle do desc "Prints out the word 'Yaffle'" task :squawk => :environment do diff --git a/railties/doc/guides/source/creating_plugins/string_to_squawk.txt b/railties/doc/guides/source/creating_plugins/string_to_squawk.txt index 50516cef69..63f1131442 100644 --- a/railties/doc/guides/source/creating_plugins/string_to_squawk.txt +++ b/railties/doc/guides/source/creating_plugins/string_to_squawk.txt @@ -10,10 +10,10 @@ Most plugins store their code classes in the plugin's lib directory. When you a First, you need to write the tests. Testing plugins is very similar to testing rails apps. The generated test file should look something like this: +*vendor/plugins/yaffle/test/core_ext_test.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/test/core_ext_test.rb - require 'test/unit' class CoreExtTest < Test::Unit::TestCase @@ -26,11 +26,10 @@ end Start off by removing the default test, and adding a require statement for your test helper. +*vendor/plugins/yaffle/test/core_ext_test.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/test/core_ext_test.rb - -require 'test/unit' require File.dirname(__FILE__) + '/test_helper.rb' class CoreExtTest < Test::Unit::TestCase @@ -53,10 +52,10 @@ No tests were specified Great - now you are ready to start development. The first thing we'll do is to add a method to String called `to_squawk` which will prefix the string with the word ``squawk!''. The test will look something like this: +*vendor/plugins/yaffle/init.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/init.rb - class CoreExtTest < Test::Unit::TestCase def test_string_should_respond_to_squawk assert_equal true, "".respond_to?(:to_squawk) @@ -72,17 +71,17 @@ class CoreExtTest < Test::Unit::TestCase end -------------------------------------------------------- +*vendor/plugins/yaffle/init.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/init.rb - require "core_ext" -------------------------------------------------------- +*vendor/plugins/yaffle/lib/core_ext.rb* + [source, ruby] -------------------------------------------------------- -# File: vendor/plugins/yaffle/lib/core_ext.rb - String.class_eval do def to_squawk "squawk! #{self}".strip diff --git a/railties/doc/guides/source/creating_plugins/view_helper.txt b/railties/doc/guides/source/creating_plugins/view_helper.txt index b03a190e1a..4eaec93824 100644 --- a/railties/doc/guides/source/creating_plugins/view_helper.txt +++ b/railties/doc/guides/source/creating_plugins/view_helper.txt @@ -8,10 +8,10 @@ Creating a view helper is a 3-step process: First, create the test to define the functionality you want: +*vendor/plugins/yaffle/test/view_helpers_test.rb* + [source, ruby] --------------------------------------------------------------- -# File: vendor/plugins/yaffle/test/view_helpers_test.rb - require File.dirname(__FILE__) + '/test_helper.rb' include YaffleViewHelper @@ -28,20 +28,20 @@ end Then add the following statements to init.rb: +*vendor/plugins/yaffle/init.rb* + [source, ruby] --------------------------------------------------------------- -# File: vendor/plugins/yaffle/init.rb - require "view_helpers" ActionView::Base.send :include, YaffleViewHelper --------------------------------------------------------------- Then add the view helpers file and +*vendor/plugins/yaffle/lib/view_helpers.rb* + [source, ruby] --------------------------------------------------------------- -# File: vendor/plugins/yaffle/lib/view_helpers.rb - module YaffleViewHelper def squawk_info_for(yaffle) returning "" do |result| -- cgit v1.2.3