Permalink
Browse files

Plugin Guide: cleaned up file paths, made formatting more consistent

  • Loading branch information...
zilkey committed Nov 12, 2008
1 parent 7f24653 commit 40bc386ed8cc403050292ab19428f1e467fa1737

Large diffs are not rendered by default.

Oops, something went wrong.
@@ -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)`.
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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|

0 comments on commit 40bc386

Please sign in to comment.