• Table of contents
• Writing plugins compatible with both Redmine 1.x and 2.x
• Routing
  • Theory
  • Code sample
• Overriding models, controllers and helpers
  • Theory
  • Code
  • Views and form tags
• Extending default helpers and controllers
• Miscellaneous
  • Links and paths to plugin assets
  • Relative url root
• Conclusion

Writing plugins compatible with both Redmine 1.x and 2.x¶

This guide is not intended to be complete and fool proof. It simply contains bits and scraps i gathered while adding Redmine 2.x (and Rails 3) compatibility to my plugins. I believe tips i give here will help create cross-version plugins.

Routing¶

Theory¶

Most simple part so far. Although routing syntax completely changed in Rails 3, it is straightforward and easy to learn. For complete guide please see http://www.engineyard.com/blog/2010/the-lowdown-on-routes-in-rails-3/ link.

Code sample¶

Below is sample routing.rb file which is compatible with both Rails' versions.

if Rails::VERSION::MAJOR >= 3
  RedmineApp::Application.routes.draw do
    match 'projects/:project_id/boards/:board_id/manage', :to => 'boards_watchers#manage', :via => [:get, :post]
    match 'projects/:project_id/boards/:board_id/manage_topic', :to => 'boards_watchers#manage_topic', :via => [:get, :post]
  end
else
  ActionController::Routing::Routes.draw do |map|
    map.with_options :controller => 'boards_watchers' do |bw_routes|
      bw_routes.with_options :conditions => {:method => :get} do |bw_views|
        bw_views.connect 'projects/:project_id/boards/:board_id/manage', :action => 'manage'
        bw_views.connect 'projects/:project_id/boards/:board_id/manage_topic', :action => 'manage_topic'
      end
      bw_routes.with_options :conditions => {:method => :post} do |bw_views|
        bw_views.connect 'projects/:project_id/boards/:board_id/manage', :action => 'manage'
        bw_views.connect 'projects/:project_id/boards/:board_id/manage_topic', :action => 'manage_topic'
      end
    end
  end
end

Overriding models, controllers and helpers¶

Theory¶

Since patching mechanism is changed in Rails 3, in order to support both Redmine version in the plugin we have to check two different code branches – one should use Dispatcher functionality (Rails 2.x) and another – new to_prepare functionality from Rails 3.

Code¶

To make things simple and clear, i moved all similar parts of the code to the separate file in lib folder, and left only Rails specific code in the init.rb file. So usual inclusion code would look like following:

init.rb:

# Including dispatcher.rb in case of Rails 2.x
require 'dispatcher' unless Rails::VERSION::MAJOR >= 3

if Rails::VERSION::MAJOR >= 3
  ActionDispatch::Callbacks.to_prepare do
    # use require_dependency if you plan to utilize development mode
    require 'boards_watchers_patches'
  end
else
  Dispatcher.to_prepare BW_AssetHelpers::PLUGIN_NAME do
    # use require_dependency if you plan to utilize development mode
    require 'boards_watchers_patches'
  end
end

boards_watchers_patches.rb:

# use require_dependency if you plan to utilize development mode
require 'application_helper'

module BoardsWatchers
  module Patches
    module ApplicationHelperPatch
      def self.included(base) # :nodoc:
        # sending instance methods to module
        base.send(:include, InstanceMethods)

        base.class_eval do
          unloadable

          # aliasing methods if needed
          alias_method_chain :render_page_hierarchy, :watchers
        end
      end

      # Instance methods are here
      module InstanceMethods
        def render_page_hierarchy_with_watchers(pages, node=nil, options={})
          # our code is here
        end
      end
    end
  end
end

# now we should include this module in ApplicationHelper module
unless ApplicationHelper.included_modules.include? BoardsWatchers::Patches::ApplicationHelperPatch
    ApplicationHelper.send(:include, BoardsWatchers::Patches::ApplicationHelperPatch)
end

Views and form tags¶

This is the part of common problem, when it is not possible to patch different parts of views files and in order to add/change couple of strings in any .erb file plugin authors have to replace whole file. I filed a ticket on redmine.org (http://www.redmine.org/issues/11104) proposing possible solution to this issue. Meanwhile i would like to ask anyone who interested in cross-version compatibility to take a look at my plugin Plugin views revisions This plugin solves this issue.

Anyway, if we are about to make existing plugin with its own views compatible with Rails 3.x, there are some things that are changed in view syntax and code.

First of all, it is the form_tag and form_for methods, In Rails 2.x we had to use <% form_for > without equal sign and in Rails 3.x we need to use equal sign: <= form_for ... %>

Another thing that is related to the views is that in Rails 3.x all strings that displayed by views are escaped by default, so you have to add manually .html_safe method if you want to return actual HTML code in your helpers.

Extending default helpers and controllers¶

In Redmine versions prior to 2.0.0 all plugins were in vendor/plugins folder and because of that Rails automatically loaded and added all files inside app/controllers, app/helpers, app/models, etc folders.

This approach allowed to extend existing controllers and helpers by simply adding appropriate files and methods to the plugin' folders. For example, if we have to add method get_list_of_projects to SettingsHelper we can simply create file named settings_helper.rb in app/helpers folder of the plugin with the following content:

app/helpers/settings_helper.rb

module SettingsHelper
  def get_list_of_projects
    # do what we need here
  end
end

Redmine 2.x moved plugins to plugins folder in application's root and because of that method described above does not work at all. So we have to use patching and override mechanisms described above to make things work.

Miscellaneous¶

Links and paths to plugin assets¶

Sometimes you need to reference some assets from plugin assets folder. If you are using Redmine 1.x it was possible to do it by using extended image_path function with extra parameter (:plugin) to get full asset path, for example:

image_path("../flash/some_flash.swf",:plugin => 'my_plugin')

Unfortunately, Redmine 2.x removed support for this function, so i wrote my own version of function which will return path to the assets. Please put file with this function into any subfolder of the plugin folder, otherwise plugin name retrieval would not work

module MyPluginAssetHelpers
  PLUGIN_NAME = File.expand_path('../../*', __FILE__).match(/.*\/(.*)\/\*$/)[1].to_sym

  def self.plugin_asset_link(asset_name,options={})
    plugin_name=(options[:plugin] ? options[:plugin] : PLUGIN_NAME)
    File.join(Redmine::Utils.relative_url_root,'plugin_assets',plugin_name.to_s,asset_name)
  end
end

Relative url root¶

If you installed Redmine to the sub-URI you should set Redmine::Utils.relative_url_root to the
value of sub-URI in config/additional_environment.rb:

Redmine::Utils::relative_url_root = "/redmine" 

Unfortunately this method does not work for Redmine 2.x and you should set ActionController root directly:

config.action_controller.relative_url_root = '/redmine'

Conclusion¶

This is all so far. Please do comment and correct this post if you would like to.

I think it would be great if something based on this post will be added to the plugins related wiki pages