From ccd9ef158953e30e66a4da143314955cd64e71c8 Mon Sep 17 00:00:00 2001 From: Jeff Dean Date: Wed, 12 Nov 2008 01:21:09 -0500 Subject: Updated preparation section of plugins guide --- .../guides/source/creating_plugins/preparation.txt | 47 ++++++++++------------ 1 file changed, 21 insertions(+), 26 deletions(-) (limited to 'railties/doc/guides/source/creating_plugins/preparation.txt') diff --git a/railties/doc/guides/source/creating_plugins/preparation.txt b/railties/doc/guides/source/creating_plugins/preparation.txt index 77e3a3561f..83717c7ac8 100644 --- a/railties/doc/guides/source/creating_plugins/preparation.txt +++ b/railties/doc/guides/source/creating_plugins/preparation.txt @@ -2,11 +2,12 @@ === Create the basic app === -In this tutorial we will create a basic rails application with 1 resource: bird. Start out by building the basic rails app: +The examples in this guide require that you have a working rails application. To create a simple rails app execute: ------------------------------------------------ -rails plugin_demo -cd plugin_demo +gem install rails +rails yaffle_guide +cd yaffle_guide script/generate scaffold bird name:string rake db:migrate script/server @@ -14,25 +15,28 @@ script/server Then navigate to http://localhost:3000/birds. Make sure you have a functioning rails app before continuing. +.Editor's note: 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. -=== Create the plugin === +=== Generate the plugin skeleton === -The built-in Rails plugin generator stubs out a new plugin. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass `\--with-generator` to add an example generator also. +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. This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories. Examples: ---------------------------------------------- -./script/generate plugin BrowserFilters -./script/generate plugin BrowserFilters --with-generator +./script/generate plugin yaffle +./script/generate plugin yaffle --with-generator ---------------------------------------------- -Later in the plugin we will create a generator, so go ahead and add the `\--with-generator` option now: +To get more detailed help on the plugin generator, type `./script/generate plugin`. + +Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the `\--with-generator` option now: ---------------------------------------------- -script/generate plugin yaffle --with-generator +./script/generate plugin yaffle --with-generator ---------------------------------------------- You should see the following output: @@ -57,19 +61,10 @@ create vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb create vendor/plugins/yaffle/generators/yaffle/USAGE ---------------------------------------------- -For this plugin you won't need the file 'vendor/plugins/yaffle/lib/yaffle.rb' so you can delete that. - ----------------------------------------------- -rm vendor/plugins/yaffle/lib/yaffle.rb ----------------------------------------------- - -.Editor's note: -NOTE: Many plugin authors prefer to keep this file, and add all of the require statements in it. That way, they only line in init.rb would be `require "yaffle"`. If you are developing a plugin that has a lot of files in the lib directory, you may want to create a subdirectory like lib/yaffle and store your files in there. That way your init.rb file stays clean - === Setup the plugin for testing === -Testing plugins that use the entire Rails stack can be complex, and the generator doesn't offer any help. In this tutorial you will learn how to test your plugin against multiple different adapters using ActiveRecord. This tutorial will not cover how to use fixtures in plugin tests. +In this guide you will learn how to test your plugin against multiple different 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: @@ -77,8 +72,6 @@ To setup your plugin to allow for easy testing you'll need to add 3 files: * A 'schema.rb' file with your table definitions. * A test helper that sets up the database before your tests. -For this plugin you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following files: - *vendor/plugins/yaffle/test/database.yml:* ---------------------------------------------- @@ -105,7 +98,9 @@ mysql: :database: yaffle_plugin_test ---------------------------------------------- -*vendor/plugins/yaffle/test/test_helper.rb:* +For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following: + +*vendor/plugins/yaffle/test/schema.rb:* [source, ruby] ---------------------------------------------- @@ -121,9 +116,12 @@ ActiveRecord::Schema.define(:version => 0) do t.datetime :last_tweeted_at end end +---------------------------------------------- -# File: vendor/plugins/yaffle/test/test_helper.rb +*vendor/plugins/yaffle/test/test_helper.rb:* +[source, ruby] +---------------------------------------------- ENV['RAILS_ENV'] = 'test' ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..' @@ -135,7 +133,6 @@ ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log") db_adapter = ENV['DB'] -# no db passed, try one of these fine config-free DBs before bombing. db_adapter ||= begin require 'rubygems' @@ -160,10 +157,8 @@ load(File.dirname(__FILE__) + "/schema.rb") require File.dirname(__FILE__) + '/../init.rb' class Hickwall < ActiveRecord::Base - acts_as_yaffle end class Wickwall < ActiveRecord::Base - acts_as_yaffle :yaffle_text_field => :last_tweet, :yaffle_date_field => :last_tweeted_at end ---------------------------------------------- -- cgit v1.2.3