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

With engines 1.2, no extra configuration in environment.rb is required. Having the plugin installed will automatically enable sharing of code within <tt>plugin/app/</tt> directories. Developers should be aware that the <tt>config.plugins</tt> parameter can be used to control plugin load order, if this is important for your application.

=== config.plugins

With Rails 1.2, the <tt>config.plugins</tt> list can be used to specify the order in which plugins are loaded. It's recommended (although not required) that you load the engines plugin first, and any other plugins later. The engines plugin enhances Rails' processing of <tt>config.plugins</tt> for occasions where you only care about the order of a small selection of your application's plugins. For instance, if you want to load +engines+ first, and anything else afterwards, then

  config.plugins = ["engines", "*"]
  
will ensure that engines is loaded first, and everything else (in whatever order Rails chooses) afterwards.

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