plugin_assets

plugin_assets helps automate the copying of plugin assets into your application’s public/ folder.

Resources

Announcement

• http://www.pluginaweek.org/2006/11/09/4-plugin_assets-give-your-plugins-value

Wiki

• http://wiki.pluginaweek.org/Plugin_assets

API

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

Development

• http://dev.pluginaweek.org/browser/trunk/plugins/action_pack/plugin_assets

Source

• http://svn.pluginaweek.org/trunk/plugins/action_pack/plugin_assets

Description

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

• images
• javascripts
• stylesheets
• etc.

Many plugins, especially those targeted for ActionPack, come bundled with additional assets that are either required or could be used by the main application. For example, a plugin that adds a helper for a js calendar could come with the required js files. These files would then be stored in your plugin_xyz/assets/javascripts/ folder.

This idea of this plugin is to provide a little more automation for copying assets from plugins to your application’s public/ folder.

Usage

Automated asset copying

Automated asset copying occurs when your Rails application starts up. Immediately after initialization, all assets from your plugins are copied to your application. You can control whether this is enabled with:

  Rails.plugins[:plugin_xyz].mirror_assets_on_initialization = true

The above will enable automated mirroring of assets for plugin_xyz. By default, it is disabled.

Write-once plugins specify which plugins should only write once to your application’s directory and never overwrite. By default, assets will always be overwritten. You can control which plugins are write-once only by:

  Rails.plugins[:plugin_xyz].write_once = true

Semi-automated asset copying

Semi-automated asset copying refers to the use of the rake tasks that come bundled with this plugin. The tasks assist in copying, updating, or listing all of the assets currently in the plugins that are being loaded. The examples in the following descriptions assuming a directory structure like the following:

  public/
  vendor/
  vendor/plugins/
  vendor/plugins/calendar_helper/
  vendor/plugins/calendar_helper/asssets/
  vendor/plugins/calendar_helper/assets/javascripts
  vendor/plugins/calendar_helper/assets/javascripts/calendar.js

assets:copy

This task will mirror assets from your plugins, overwriting any and all existing files. For example,

  rake assets:copy

  Mirroring assets for calendar_helper:
  create C:/Projects/workspace/sandbox/config/../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 C:/Projects/workspace/sandbox/config/../public/javascripts/calendar.js ...done

assets:update

This task will mirror assets from your plugins, skipping any files that already exist, regardless of whether they are different. For example, if no files have already been copied,

  rake assets:update

  Mirroring assets for calendar_helper:
  create C:/Projects/workspace/sandbox/config/../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

Additional information

Explicitly specifying plugins

For all tasks, you can specify which plugins to update by using the PLUGIN option, e.g.

  rake assets:copy PLUGIN=calendar_helper
  rake assets:update PLUGIN=calendar_helper,xyz_helper
  rake assets:list PLUGIN=calendar_helper,xyz_helper

Setting asset namespaces

By default, a plugin’s assets are copied to public/images/*, public/css/*, etc. You can control if the plugin exists in a specific namespace by setting the following:

  Rails.plugins[:plugin_xyz].asset_namespace = 'foo'

This will instruct the plugin to copy it’s assets to public/images/foo/*, public/css/foo/*, etc.

Testing

To test this plugin, the following gems must be installed:

• plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]

Dependencies

This plugin depends on the presence of the following plugins:

• loaded_plugins[http://wiki.pluginaweek.org/Loaded_plugins]

References

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

Owner: Aaron Pfeifer, Neil Abraham

Home: http://wiki.pluginaweek.org/Plugin_assets

Repository: http://svn.pluginaweek.org/trunk/plugins/action_pack/plugin_assets

License: Rails' (MIT)

Category: Assets