path: root/railties/doc/guides/source/creating_plugins/preparation.txt

== Preparation ==

=== Create the basic app ===

The examples in this guide require that you have a working rails application.  To create a simple rails app execute:

------------------------------------------------
gem install rails
rails yaffle_guide
cd yaffle_guide
script/generate scaffold bird name:string
rake db:migrate
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.


=== 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.

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 yaffle
./script/generate plugin yaffle --with-generator
----------------------------------------------

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
----------------------------------------------

You should see the following output:

----------------------------------------------
create  vendor/plugins/yaffle/lib
create  vendor/plugins/yaffle/tasks
create  vendor/plugins/yaffle/test
create  vendor/plugins/yaffle/README
create  vendor/plugins/yaffle/MIT-LICENSE
create  vendor/plugins/yaffle/Rakefile
create  vendor/plugins/yaffle/init.rb
create  vendor/plugins/yaffle/install.rb
create  vendor/plugins/yaffle/uninstall.rb
create  vendor/plugins/yaffle/lib/yaffle.rb
create  vendor/plugins/yaffle/tasks/yaffle_tasks.rake
create  vendor/plugins/yaffle/test/core_ext_test.rb
create  vendor/plugins/yaffle/generators
create  vendor/plugins/yaffle/generators/yaffle
create  vendor/plugins/yaffle/generators/yaffle/templates
create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
create  vendor/plugins/yaffle/generators/yaffle/USAGE
----------------------------------------------


=== Setup the plugin for testing ===

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:

 * A 'database.yml' file with all of your connection strings.
 * A 'schema.rb' file with your table definitions.
 * A test helper that sets up the database before your tests.

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

----------------------------------------------
sqlite:
  :adapter: sqlite
  :dbfile: yaffle_plugin.sqlite.db

sqlite3:
  :adapter: sqlite3
  :dbfile: yaffle_plugin.sqlite3.db

postgresql:
  :adapter: postgresql
  :username: postgres
  :password: postgres
  :database: yaffle_plugin_test
  :min_messages: ERROR

mysql:
  :adapter: mysql
  :host: localhost
  :username: rails
  :password:
  :database: yaffle_plugin_test
----------------------------------------------

For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:

*vendor/plugins/yaffle/test/schema.rb:*

[source, ruby]
----------------------------------------------
ActiveRecord::Schema.define(:version => 0) do
  create_table :hickwalls, :force => true do |t|
    t.string :name
    t.string :last_squawk
    t.datetime :last_squawked_at
  end
  create_table :wickwalls, :force => true do |t|
    t.string :name
    t.string :last_tweet
    t.datetime :last_tweeted_at
  end
end
----------------------------------------------

*vendor/plugins/yaffle/test/test_helper.rb:*

[source, ruby]
----------------------------------------------
ENV['RAILS_ENV'] = 'test'
ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'

require 'test/unit'
require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))

config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")

db_adapter = ENV['DB']

db_adapter ||=
  begin
    require 'rubygems'
    require 'sqlite'
    'sqlite'
  rescue MissingSourceFile
    begin
      require 'sqlite3'
      'sqlite3'
    rescue MissingSourceFile
    end
  end

if db_adapter.nil?
  raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
end

ActiveRecord::Base.establish_connection(config[db_adapter])

load(File.dirname(__FILE__) + "/schema.rb")

require File.dirname(__FILE__) + '/../init.rb'

class Hickwall < ActiveRecord::Base
end

class Wickwall < ActiveRecord::Base
end
----------------------------------------------