= Upgrading from Engines 1.1.x to Engines 1.2.x


The 1.2 release of the engines plugin represents a significant rewrite of the internals. Now less intrusive into the core frameworks, it's even simpler for plugin developers to make more flexible plugins than Rails typically allows.

However, as a consequence of change, you may need to make some adjustments to your application to get the most benefit. These are outlined below:


== In your application

The following changes will affect code in applications which use the engines plugin

=== Change the engine_schema table to plugin_schema

Because the engines plugin now works universally for any Rails plugin, the table used to store migration information has been renamed appropriately. We can also play nicely with other plugin_migration implementations by supporting this convention.


=== Rename RAILS_ROOT/public/engine_files to RAILS_ROOT/public/plugin_assets

Similarly, any plugin can now share stylesheets, images and so on via an assets folder, so the destination within the main public directory has been renamed to reflect this. You can simply delete the RAILS_ROOT/public/engine_files directory; the new one will be generated the next time your application starts.


=== The engine_image, engine_stylesheet and engine_javascript helpers have been replaced with enhanced versions of the normal Rails asset helpers

Now, it's simple to include an image from any plugin, by adding a plugin key to the helper's options hash:

  image_tag "image.png", :plugin => "my_plugin"

A similar convention exists for stylesheets and javascript files. Additionally, the old behaviour of automatically including assets which match the "engine"'s name has been dropped - only the files you explicitly request are included.


=== Engines.start is replaced with config.plugins

Rails' native configuration object now includes an array for specifying which plugins are loaded, and in what order. The engines plugin enhances this feature with a "*" wildcard, so that you can load any order-sensitive plugins, and then the rest in any order.

  config.plugins = ["engines", "some_plugin", "another_plugin", "*"]
  
It's worth noting that the engines plugin no longer needs to be specifically loaded first, so most people can happily ignore the config.plugins array without any problems.


=== The "config" method for "engine"-style configuration is no longer loaded by default. 

See below.
  
  
=== Any "engines" type rake tasks are now "plugin" tasks.

The following rake tasks are now provided by the engines plugin for operating on your application's plugins (whenever a task can operate on a single plugin, this can be controlled by specifying PLUGIN=<name> on the commandline):
  
  db:fixtures:plugins:load  # load fixtures from plugins. 
  
  test:plugins:units        # Run tests from within <plugins>/test/units
  test:plugins:functional   # Run tests from within <plugins>/test/functional
  test:plugins:integration  # Run tests from within <plugins>/test/integration
  test:plugins              # Run all tests from within <plugins>/test/*

  doc:plugins               # Run full rdoc against all source files within all plugins
  doc:plugins:<plugin>      # Run full rdoc against all source files within the given plugin



== In your "engine"-style plugins

If you have developed or are using plugins that leverage engines enhancements, you need to be aware of the following changes in engines 1.2.

=== init_engine.rb is no longer required

Please now create init.rb files, just as you'd find in "normal" plugins. Remember - there's no such thing as "an engine" anymore.


=== The "fixture" method for loading tests from arbitrary files

Supporting this was just too difficult, and it seems like the combination of Rails' own lack of enhancements regarding this feature, along with the mind-shift against static fixtures, meant that it simply was too much work to continue to support.

The only reason this mechanism originally existed was to support plugins which couldn't predict the names of the tables that models might be stored in. This is now a discouraged behaviour.


=== Engines.current.version has changed its behaviour slightly.

The engines plugin used to provide a simple way to store version information about plugins. This has now been superceded by including that information in an about.yml file, which any plugin can use.


=== The "config" method is not included, by default.

Where previously developers could use the "config" method to define configuration, this is now deprecated in favour of using mattr_accessor directly in the Module. However, if you still *need* to use the config method, it is included but must be explicitly required, probably near the top of environment.rb:
  
  require File.join(RAILS_ROOT, "vendor", "plugins", "engines",
                    "lib", "engines", "deprecated_config_support")


=== Public assets should now be stored in a subdirectory of your plugin called "assets", rather than "public".

This clarifies the nature of this directory; it is not made public itself, but rather is a container for files which should be made accessible from the web.