= Desert - It doesn't get any DRYer than this

Desert is a Rails plugin framework that makes it easy to share models, views, 
controllers, helpers, routes, and migrations across your applications.

With Desert, reusability doesn't come at the cost of extensibility: it's trivial to extend 
the functionality of a plugin - both in your application _and_ in other plugins.

Classes are automatically mixed in with your own or other plugins' classes.
This allows you to make full featured composable components.

Desert is a replacement for Appable Plugins (http://wiki.pluginaweek.org/Appable_plugins).

== Anatomy of a desert plugin

  |-- app
  |   |-- controllers
  |   |   |-- application.rb
  |   |   `-- blogs_controller.rb
  |   |-- helpers
  |   |   |-- application_helper.rb
  |   |   `-- blogs_helper.rb
  |   |-- models
  |   |   `-- user.rb
  |   `-- views
  |       |-- blogs
  |       |-- layouts
  |       |   `-- users.html.erb
  |       `-- users
  |           |-- index.html.erb
  |           `-- show.html.erb
  |-- db
  |   `-- migrate
  |       `-- 001_migrate_users_to_001.rb
  |-- lib
  |   `-- current_user.rb
  |-- spec
  |   |-- controllers
  |   |   `-- blogs_controller_spec.rb
  |   |-- fixtures
  |   |-- models
  |   |-- spec_helper.rb
  |   `-- views
  |       `-- blogs
  `-- vendor
      `-- plugins
          `-- user
              |-- app
              |   |-- controllers
              |   |   `-- users_controller.rb
              |   |-- helpers
              |   |   `-- users_helper.rb
              |   |-- models
              |   |   `-- user.rb
              |   `-- views
              |       `-- users
              |           |-- edit.html.erb
              |           |-- index.html.erb
              |           |-- new.html.erb
              |           `-- show.html.erb
              |-- config
              |   `-- routes.rb
              |-- db
              |   `-- migrate
              |       `-- 001_create_users.rb
              |-- init.rb
              |-- lib
              |   `-- current_user.rb
              |-- spec
              |   |-- controllers
              |   |   `-- user_controller_spec.rb
              |   |-- fixtures
              |   |   `-- users.yml
              |   |-- models
              |   |   `-- user.rb
              |   |-- spec_helper.rb
              |   `-- views
              |       `-- users
              `-- tasks

== Installation and Usage

* Install the gem

    sudo gem install desert

* Require 'desert' between 'boot' and Rails::Initializer.run in environment.rb

    # File: config/environment.rb

    require File.join(File.dirname(__FILE__), 'boot')

    require 'desert'

    Rails::Initializer.run do |config|
    end
  
NOTE: you may have to require rubygems before requiring desert.

* Generate your desert plugin

    script/generate desert_plugin my_plugin_app

== Manage Plugin Dependencies

By default, Rails loads plugins in alphabetical order, making it tedious to manage dependencies.
Desert will automatically load plugins in the proper order when you declare their dependencies like this:

    # File: vendor/plugins/blogs/init.rb

    require_plugin 'user'
    require_plugin 'will_paginate'

Here <tt>user</tt> and <tt>will_paginate</tt> will always be loaded before <tt>blogs<tt>. Note that any plugin can be 
declared as a dependency.

== Share Routes

When you share controllers, you'll want to share their routes too.  
If you look in your RAILS_ROOT/config/routes.rb file you will notice that the generator added a new line to the top:

    map.routes_from_plugin(:my_plugin_app)

In the <tt>user</tt> plugin: 

    # File: vendor/plugins/user/config/routes.rb

    resource :users

In the <tt>blogs</tt> plugin:

    File: vendor/plugins/blogs/config/routes.rb

    resource :blogs

In the application:
  
    # File: config/routes.rb

    ActionController::Routing::Routes.draw do |map|
      map.routes_from_plugin :blogs
      map.routes_from_plugin :user
    end

Here the application adds the <tt>users</tt> resource from the <tt>user</tt> plugin and the <tt>blogs</tt> resource from 
the <tt>blogs</tt> plugin.
Notice that there is no need to call methods on map in the plugin route files, because they are instance eval'd in the 
map object.

All standard routing methods are available in your plugin's routes file, such as:

    namespace :admin do |admin|
      admin.resources :posts
    end

Desert uses a separate table to manage migration version to maintain backwards compatibility with Rails 1.x.
Your plugin app's migration live in your_plugin/db/migrate.  To run migrations, follow these steps:

* Create a new migration in your main app

    script/generate migration migrate_my_plugin_to_045
  
* Add the custom `migrate_plugin` method

    class MigrateMyPluginTo045 < ActiveRecord::Migration
      def self.up
        migrate_plugin(:my_plugin, 20080530223548)
      end

      def self.down
        migrate_plugin(:my_plugin, 0)
      end
    end

* Run your migrations normally

    rake db:migrate

    connect "/signup", :controller => "users", :action => "signup"

== Share Migrations

Sharing models means sharing schema fragments, and that means sharing migrations:

In the <tt>user</tt> plugin:

  vendor/plugins/user/db/migrate/
    001_create_user_table.rb

In the <tt>blogs</tt> plugin:

    vendor/plugins/blogs/db/migrate/
      001_create_user_table.rb
      002_add_became_a_blogger_at_to_user.rb

Here the <tt>blogs</tt> plugin needs to add a column to the <tt>users</tt> table. No problem!
It just includes a migration in its <tt>db/migrate</tt> directory, just like a regular Rails application.
When the application developer installs the plugin, he migrates the plugin in his own migration:

<tt>application_root/db/migrate/009_install_user_and_blogs_plugins.rb</tt>

    class InstallUserAndBlogsPlugins < ActiveRecord::Migration
      def self.up
        migrate_plugin 'user', 1
        migrate_plugin :blogs, 2
      end

      def self.down
        migrate_plugin 'user', 0
        migrate_plugin :blogs, 0
      end
    end

Here the application migrates the <tt>user</tt> plugin to version 1 and the <tt>blogs</tt> plugin to version 2.
If a subsequent version of the plugin introduces new migrations, the application developer has full control over when to 
apply them to his schema.

== Share Views

To share views, just create templates and partials in the plugin's <tt>app/views</tt> directory, just as you would with 
a Rails application.

<tt>application_root/app/views/blogs/index.html.erb</tt>

    <%= @blog.posts.each do |post| %>
      ...
    <% end %>

== Customize / extend behavior in each installation

Say you want to create a plugin named acts_as_spiffy.
Desert allows Spiffy to have a set of features that can be reused and extended in several projects.

The Spiffy project has a:

* SpiffyController
* Spiffy model
* SpiffyHelper
* spiffy.html.erb
* SpiffyLib library class

The Spiffy plugin acts as its own mini Rails application.  Here is the directory structure:

  RAILS_ROOT/vendor/plugins/spiffy/app/controllers/spiffy_controller.rb
  RAILS_ROOT/vendor/plugins/spiffy/app/models/spiffy.rb
  RAILS_ROOT/vendor/plugins/spiffy/app/helpers/spiffy_helper.rb
  RAILS_ROOT/vendor/plugins/spiffy/app/views/spiffy/spiffy.rhtml
  RAILS_ROOT/vendor/plugins/spiffy/lib/spiffy_lib.rb

Now, say there is a Spiffy Store rails application that uses acts_as_spiffy.  The Rails app can open up any of the 
Spiffy classes and override any of the methods.

Say spiffy.rb in the Spiffy plugin is defined as:

  class Spiffy < ActiveRecord::Base
    def why?
      "I just am Spiffy"
    end
  end

The Spiffy#why method can be overridden in RAILS_ROOT/app/models/spiffy.rb

  class Spiffy < ActiveRecord::Base
    def why?
      "I sell Spiffy stuff"
    end
  end

== Running plugin tests

You can run your plugin tests/specs like so:

  rake desert:testspec:plugins PLUGIN=spiffy

Leaving off the PLUGIN environment variable will cause it to run all the
test/specs for all installed plugins, which may not be what you want.

== Running Desert Specs

To run specs, you need to:

* Make sure you have the necessary gems installed (rr, rspec)
* Install git http://git.or.cz/
* Create a database named desert_test
* Update the database.yml file in <tt>spec/rails_root/config/database.yml</tt>
* Install the dependencies
* Run the specs

Desert is a library that heavily monkey patches Rails. To ensure that Desert works with
multiple versions of Rails, its tests are run against the supported versions of Rails.

To set up the different supported versions of Rails, run

  rake install_dependencies

This will clone the Rails git repo and export the supported versions of rails into the
respective directories.

  rake update_dependencies

will update the clones repo on your machine.