plugins_plus

plugins_plus adds various abilities to plugins, including asset management, migrations, and application code integration.

Resources

API

• http://api.pluginaweek.org/plugins_plus

Bugs

• http://pluginaweek.lighthouseapp.com/projects/13284-plugins_plus

Development

• http://github.com/pluginaweek/plugins_plus

Source

• git://github.com/pluginaweek/plugins_plus.git

Description

If you’re building a product line or even a group of Rails applications, you may find that you’re duplicating models, views, controllers, etc. throughout these applications. This can become difficult to maintain unless this common code can be shared via a single source.

Plugins are a good place for this abstraction, but do not currently have built-in support to easily integrate it with your core application. plugins_plus makes this possible by allowing plugins to act as sort of "mini-applications" by adding support for the following:

• Asset management - Keeping the application’s assets up-to-date with plugin assets
• Migrations - Migrating database changes for a particular plugin
• Application code integration - Managing a plugin’s mvc code into a similar app/models, app/controllers, etc. structure

Installation

Besides installing the plugin, you must add a "boot" process to your environment’s configuration if you’re using any of the Application code integration features. To do this, change your config/environment.rb to look like so:

  require 'config/boot'
  require 'vendor/plugins/plugins_plus/boot'

  ...

  Rails::Initialize.run do |config|
    ...
  end

This makes sure that plugins_plus hooks into the Rails framework before any part of the initialization process is begun.

Note that this must be installed as a plugin and not a gem.

Examples

Below are a few scenarios of how plugins_plus can be used.

The "users" plugin

Consider a "users" plugin you want to create because the way you handle users is common throughout multiple projects at your company. Below is a possible file structure for that plugin:

  users/
  users/app/
  users/app/controllers/
  users/app/controllers/users_controller.rb
  users/app/models/
  users/app/models/user.rb
  users/app/views/
  users/app/views/layouts/
  users/app/views/layouts/users.html.erb
  users/app/views/users/edit.html.erb
  users/app/views/users/index.html.erb
  users/app/views/users/new.html.erb
  users/app/views/users/show.html.erb
  users/assets/
  users/assets/images/
  users/assets/images/profile.png
  users/assets/stylesheets/
  users/assets/stylesheets/users.css
  users/db/
  users/db/migrate/
  users/db/migrate/001_create_users.rb
  users/db/migrate/002_add_user_passwords.rb
  users/init.rb
  users/routes.rb

In this plugin, we’ve defined:

• Controllers
• Models
• Views
• Image/Stylesheet Assets
• Database migrations
• Routes

First, make sure you’ve followed the installation process for plugins_plus described in this README.

To migrate your "users" plugin within your application, run the following:

  ./script/generate plugin_migration users

This creates the MigrateUsersToVersion2 migration in db/migrate/001_migrate_users_to_version_2.rb. If you have existing migrations, it will adjust the filename appropriately.

Once the migrations are generated, you’ll probably want to copy over the assets. To do so, run the following:

  rake assets:copy

  Mirroring assets for users:
  create /path/to/project/public/images/profile.png ...done
  create /path/to/project/public/stylesheets/profile.css ...done

Now all of your assets have been copied to your main application’s public folder.

Next, you’ll probably want to make sure that all of the routes for your plugin have been defined. To do so, add the following to your config/routes.rb:

  ActionController::Routing::Routes.draw do |map|
    map.from_plugin :users
  end

So far you’ve:

1. Created your migrations
2. Copied over assets
3. Configured routes to the plugin

Now you’re all set! All of the load paths are automatically set up by plugins_plus, so there’s no need to do any more configuration. Congratulations!

The "organized" application

plugins_plus isn’t just helpful for sharing code across multiple applications; it’s also helpful for organizing a single application’s code. Say you’re creating a website that has a few distinct groups of functionality:

• Platform - Hosts your api code
• User Community - Provides social networking features to your users
• Partner Community - Provides management for your partners

These are 3 distinct groups of functionality which may or may not shared common code. However, you want to separate out their models, views, and related controllers so that you feel better organized.

Below is a possible file structure for your application:

  /
  /apps/
  /apps/partners/
  /apps/partners/app/
  /apps/partners/app/controllers/
  /apps/partners/app/controllers/partners_controller.rb
  /apps/partners/app/models/
  /apps/partners/app/models/partner.rb
  /apps/partners/app/views/
  /apps/partners/app/views/partners/
  /apps/partners/routes.rb
  /apps/platform/app/
  /apps/platform/app/controllers/
  /apps/platform/app/controllers/items_controller.rb
  /apps/platform/app/models/
  /apps/platform/app/models/item.rb
  /apps/platform/routes.rb
  /apps/users/app/
  /apps/users/app/controllers/
  /apps/users/app/controllers/users_controller.rb
  /apps/users/app/models/
  /apps/users/app/models/user.rb
  /apps/users/app/views/
  /apps/users/app/views/users/
  /apps/users/app/views/users/index.html.erb
  /apps/users/routes.rb
  /config/routes.rb
  /db/
  /db/migrate/
  /db/migrate/001_create_users.rb
  /db/migrate/002_create_items.rb
  /db/migrate/003_create_partners.rb

In this example, we’ve created 3 plugins: partners, platform, and users. Each have their own separate directory structures for managing models, views, controllers, routes, etc.

To configure Rails to look for plugins under the "apps" directory, add the following to config/environment.rb:

  Rails::Initialize.run do |config|
    ...
    config.plugin_paths << "#{Rails.root}/apps"
    ..
  end

Once this is in place, you can follow the same procedure as described in the first "users" example for copying assets and setting up routes. We’ve decided to keep migrations in the main application since putting them in each individual plugin would probably make things more difficult in the long run.

Congratulations! You’ve just reorganized your application code!

Usage

Application Code Integration

Application code integration adds support for integrating:

• Models
• Views
• Controllers
• Routes
• ActionMailer templates

All of these files should be organized in a similar directory structure to your core application, but under the plugin’s root directory.

Routes

Custom plugin routes are defined under vendor/plugins/users/routes.rb like so:

  map.resources :users
  map.resources :sessions

To load these defined routes from your main application’s routes configuration, add the following to config/routes.rb:

  ActionController::Routing::Routes.draw do |map|
    ...
    map.from_plugin :users
    ...
  end

Conflicting code

If there is more than one plugin that defines a particular models/controller/view/etc., then priority will be determined by the order in which the plugins were loaded. For example, if both a users plugin and authenticated_users plugin defined a User model, but authenticated_users was loaded after users, then the User model from authenticated_users will be used.

NOTE There is no support for automatic code mixing of models/controllers. You must use modules for this.

Assets

Assets are another name for the files you would normally find under your application’s public/ folder. This includes:

• images
• javascripts
• stylesheets
• etc.

assets:copy

Mirrors assets from your plugins, overwriting any and all existing files.

  rake assets:copy

  Mirroring assets for calendar_helper:
  create /path/to/project/public/javascripts/calendar.js ...done

If the calendar.js already existed, the file would be overwritten:

  rake assets:copy

  Mirroring assets for calendar_helper:
  update /path/to/project/public/javascripts/calendar.js ...done

assets:update

Mirrors assets from your plugins, skipping any files that already exist. For example, if no files have already been copied:

  rake assets:update

  Mirroring assets for calendar_helper:
  create /path/to/project/public/javascripts/calendar.js ...done

However, if the calendar.js already existed, the file would be skiped:

  rake assets:update

  Mirroring assets for calendar_helper:
  No new assets found

assets:list

This task will list all of the available assets for your plugins. For example,

  rake assets:list

  calendar_helper:
  vendor/plugins/calendar_helper/assets/javascripts
  vendor/plugins/calendar_helper/assets/javascripts/calendar.js

Migrations

Adds a new table called plugin_schema_info to track plugin migration versions:

  plugin_schema_info
  ------------------
  plugin_name (string)
  version (integer)

Migrations are expected to be located in /db/migrate in your plugin’s folder.

script/generate plugin_migration

Generates a migration that updates the plugin’s schema to the latest version.

For example,

  ./script/generate plugin_migration has_comments

With 4 existing migrations, this creates the MigrateHasCommentsToVersion5 migration in db/migrate/005_migrate_has_comments_to_version_5.rb

Testing

Before you can run any tests, the following gems must be installed:

• plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

Dependencies

• Rails 2.1 or later

References

• James Adam - Engines[http://www.rails-engines.org]