Redmine Plugin Extension and Development: If you'd like to customize Redmine to meet your own precise project management needs, this is the ideal guide to understanding and realizing the full potential of plugins. Full of real-world examples and clear instructions.

The version or versions of Redmine that a plugin is compatible with can be specified within the plugin initialization file using the requires_redmine helper.

This helper allows the plugin author to alert Redmine system administrators that the plugin is not intended to run with the administrator's version of Redmine. Some examples of the types of version checks that can be performed are as follows:

Similar to the requires_redmine helper, the requires_redmine_plugin function is used to limit the successful deployment of our plugin based on the availability of another Redmine plugin.

The following examples are based on a plugin named :sample_plugin being included for availability and version checks:

The menu helper, which is also aliased to add_menu_item, allows us to inject custom entries into various content areas of Redmine. The syntax for adding a menu item is:

menu(menu, item, url, options = {})

The options hash can accept any number of the following parameters:

Redmine also provides a function we can use in our plugin to remove menu items, the syntax for which is:

delete_menu_item(menu, item)

The following example injects an entry into the project menu. Note that although you've added a new menu item, it may still not be available to all users due to insufficient permissions.

menu :project_menu, 
  :articles, 
  { :controller => 'articles', :action => 'index' }, 
  :caption => :knowledgebase_title, 
  :after => :activity, 
  :param => :project_id

The other valid targets for the menu are admin_menu, top_menu, account_menu, and application_menu.

The admin_menu target is used to add custom entries to the Administration menu, which is available at http://localhost:3000/admin, and can insert custom entries between the Settings and Plugins menu items.

The permission helper is used to define a named permission for the given actions. The syntax for this helper is:

permission(name, actions, options = {})

The actions argument is a hash with controllers as keys and actions as values (a single value or an array):

  permission :destroy_contacts, { :contacts => :destroy }
  permission :view_contacts,    { :contacts => [:index, :show] }

The valid options are as follows:

Permissions will be covered in more detail in Chapter 3, Permissions and Security.

If our plugin will be adding functionality at the project level (as opposed to globally) within Redmine, we'll need to define a project_module block.

A project module is effectively a functional area within Redmine whose data belongs to a specific project, or whose scope can be limited to a project. Examples of project modules are issues, documents, wikis, or time tracking features.

Permissions defined within the project_module block will be bound to the module, as follows:

project_module :knowledgebase do
  permission :view_articles, {
    :knowledgebase => :index,
    :articles      => [:show, :tagged],
    :categories    => [:index, :show]
  }
  permission :comment_and_rate_articles, {
    :knowledgebase => :index,
    :articles      => [:show, :tagged, :rate, :comment, :add_comment],
    :categories    => [:index, :show]
  }
  # ...
end

Activity providers are essentially models that have been defined to provide events to the activity fetcher. Once a model has registered an activity provider, activities will be mixed into a project's activity stream.

A model can provide several activity event types, which are registered by passing event types and optional class names to the activity_provider helper plugin:

  activity_provider :news
  activity_provider :scrums, :class_name => 'Meeting'
  activity_provider :issues, :class_name => ['Issue', 'Journal']

Using the activity_provider helper simply indicates that there are activity providers registered. The syntax for the helper functions is:

activity_provider(*args)

The helper simply wraps Redmine::Activity.register, which is available at /path/to/redmine/lib/redmine/activity.rb.

A matching acts_as_activity_provider entity must be initialized at the model level in order to actually utilize this functionality.

We will cover activity provider configuration in more detail in Chapter 6, Interacting with the Activity Stream.

Our knowledgebase plugin will be used to create articles, which we may want to reference in other Redmine content areas.

For example, if we want to register the kb#1 macro to link to a knowledgebase article with an ID value of 1, we would first need to register the macro with a Redmine::WikiFormatting::Macros.register block similar to the following:

Redmine::WikiFormatting::Macros.register do
  desc "Knowledge base Article link Macro, using the kb# format"
  macro :kb do |obj, args|
    args, options = extract_macro_options(args, :parent)
    raise 'One argument expected' if args.size != 1
    article = KbArticle.find(args.first)
    link_to_article(article)
  end
end

We could now include the text kb#1 in an issue, document, wiki, or anywhere else where Redmine formats text (see http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting for existing formatting options) and it would render as a link back to our knowledgebase article.