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: See Engines::RailsExtensions::Templates 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. Look here for more information - 
http://rails-engines.org/development/common-issues-when-overloading-code-from-plugins/

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