= IMPORTANT

Engines have been partially integrated into Rails 3.0, and fully integrated into Rails 3.1; I strongly suggest you upgrade and use the native engines features in those releases, rather than using this (increasingly out of date) plugin.

However, if you *must* use Rails 2.3 or earlier, you may still find this plugin useful.

= Old preamble

The engines plugin enhances Rails' own plugin framework, making it simple to share controllers, helpers, models, public assets, routes and migrations in plugins.

For more information, see http://rails-engines.org

= Using the plugin

Once you've installed the engines plugin, you'll need to add a single line to the top of config/environment.rb:

  require File.join(File.dirname(__FILE__), '../vendor/plugins/engines/boot')
  
You should add this line just below the require for Rails' own boot.rb file. This will enabled the enhanced plugin loading mechanism automatically for you (i.e. you don't need to set config.plugin_loader manually).

With that aside, you're now ready to start using more powerful plugins in your application. Read on to find out more about what the engines plugin enables.


== Better plugins

In addition to the regular set of plugin-supported files (lib, init.rb, tasks, generators, tests), plugins can carry the following when the engines plugin is also installed.


=== Controllers, Helpers, and Views

Include these files in an <tt>app</tt> directory just like you would in a normal Rails application. If you need to override a method, view or partial, create the corresponding file in your main <tt>app</tt> directory and it will be used instead.

* Controllers & Helpers: See Engines::RailsExtensions::Dependencies for more information.
* Views: now handled almost entirely by ActionView itself (see Engines::Plugin#add_plugin_view_paths for more information)

=== Models

Model code can similarly be placed in an <tt>app/models/</tt> directory. Unfortunately, it's not possible to automatically override methods within a model; if your application needs to change the way a model behaves, consider creating a subclass, or replacing the model entirely within your application's <tt>app/models/</tt> directory. See Engines::RailsExtensions::Dependencies for more information.

IMPORTANT NOTE: when you load code from within plugins, it is typically not handled well by Rails in terms of unloading and reloading changes. If you try to overload models like this:

    require "user" 

    class User < ActiveRecord::Base
      def your_new_method()
        # anything
      end
    end
    
... you will encounter problems in development mode. This is because you have circumvented Rails’ dependency mechanism with the explicit require, which will produce a User class that Rails has not marked as reloadable.

If you choose to use this style of overriding, you must use require_dependency rather than require to inform Rails that you are loading the class:

    require_dependency "user"

    class User < ActiveRecord::Base
      def your_new_method()
        # anything
      end
    end

=== Routes

Include your route declarations in a <tt>routes.rb</tt> file at the root of your plugins, e.g.:

  connect "/my/url", :controller => "some_controller"
  my_named_route "do_stuff", :controller => "blah", :action => "stuff"
  # etc.
  
You can then load these files into your application by declaring their inclusion in the application's <tt>config/routes.rb</tt>:

  map.from_plugin :plugin_name

See Engines::RailsExtensions::Routing for more information.
  
=== Migrations

Migrations record the changes in your database as your application evolves. With engines 1.2, migrations from plugins can also join in this evolution as first-class entities. To add migrations to a plugin, include a <tt>db/migrate/</tt> folder and add migrations there as normal. These migrations can then be integrated into the main flow of database evolution by running the plugin_migration generator:

  script/generate plugin_migration
  
This will produce a migration in your application. Running this migration (via <tt>rake db:migrate</tt>, as normal) will migrate the database according to the latest migrations in each plugin. See Engines::RailsExtensions::Migrations for more information.


=== More powerful Rake tasks

The engines plugin enhances and adds to the suite of default rake tasks for working with plugins. The <tt>doc:plugins</tt> task now includes controllers, helpers and models under <tt>app</tt>, and anything other code found under the plugin's <tt>code_paths</tt> attribute. New testing tasks have been added to run unit, functional and integration tests from plugins, whilst making it easier to load fixtures from plugins. See Engines::Testing for more details about testing, and run

  rake -T
  
to see the set of rake tasks available.

= Testing the engines plugin itself

Because of the way the engines plugin modifies Rails, the simplest way to consistently test it against multiple versions is by generating a test harness application - a full Rails application that includes tests to verify the engines plugin behaviour in a real, running environment.

Run the tests like this:

  $ cd engines
  $ rake test
  
This will generate a test_app directory within the engines plugin (using the default 'rails' command), import tests and code into that application and then run the test suite.

If you wish to test against a specific version of Rails, run the tests with the RAILS environment variable set to the local directory containing your Rails checkout

  $ rake test RAILS=/Users/james/Code/rails_edge_checkout
  
Alternatively, you can clone the latest version of Rails ('edge rails') from github like so:

  $ rake test RAILS=edge