Redmine Plugin Extension and Development

4.5 (2 reviews total)
By Alex Bevilacqua
  • Instant online access to over 8,000+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Introduction to Redmine Plugins

About this book

Redmine is a flexible project management web application that is cross-platform and cross-database. Redmine handles multiple projects and provides integrated project management features, issue tracking, and support for various version control systems.

This book provides an overview of the tools available to potential plugin authors who want to extend and enhance a product to work their way. It is meant to teach developers who have existing Ruby on Rails experience on how they can properly extend Redmine through custom plugins.

In this book, existing models, views, and controllers will be extended through the use of hooks. You will learn how custom updates can be tied into project and system activity streams.

Plugin models will be made searchable and custom permissions and security will be discussed. This book will also teach you how to create a sustainable plugin for an established product and maintain an ongoing relationship with the Redmine community as it relates to a new plugin.

Reading this book will provide you with the necessary skills to quickly and efficiently extend products through plugins.

Publication date:
March 2014
Publisher
Packt
Pages
114
ISBN
9781783288748

 

Chapter 1. Introduction to Redmine Plugins

Redmine is an open source project management platform written in Ruby and built using the Ruby on Rails framework. It currently supports a lot of key features that a software project manager would find useful, such as an issue track, wiki, time tracking, source control management integration, and various other tools that assist with document and information management.

As the product has gotten more popular, the need to extend the basic functionality through the use of third-party plugins has grown. Redmine facilitates this through a plugin API that assists in hooking external model, view, and controller code into Redmine, as well as integrating with various system features.

This chapter will introduce you to Redmine's plugin structure, as well as how to generate a new plugin, and some preliminary initialization and configuration settings. We will generate a sample plugin that we'll be using throughout this book to illustrate various code samples and topics.

The following topics will be covered in this chapter:

  • Basic plugin generation and layout

  • A brief overview of the sample plugin that will be referenced throughout this book

  • Overview of the initialization attributes

  • Introduction to some helper functions that are available to plugin authors

 

An introduction to our sample plugin


Throughout this book, we'll be returning to a sample plugin, a knowledgebase, to provide additional insight into a topic, or to provide code samples. The plugin we're discussing has actually been developed over a number of years, and has numerous contributors.

For the purposes of this book and any future examples, our knowledgebase is a plugin that offers a hybrid solution that lies somewhere between Redmine's wiki and document functionality.

It allows us to create articles that can be stored within categories. Categories are stored in a hierarchical fashion, so a category "tree" can be presented to users on the knowledgebase landing page, as seen in the following screenshot:

 

Generating a new plugin


Out of the box, Redmine provides a number of generators to facilitate the creation of plugins and plugin resources.

Note

The Redmine project website provides a plugin tutorial at http://www.redmine.org/projects/redmine/wiki/Plugin_Tutorial, which serves as a good starting point to quickly get started.

Running rails generate from the root of our Redmine installation will provide a list of available generators (truncated in the following snippet to list only those that are currently relevant):

$ rails generate
RedminePlugin:
  redmine_plugin
RedminePluginController:
  redmine_plugin_controller

RedminePluginModel:
  redmine_plugin_model

Tip

Downloading the example code

This book continually references a sample plugin known as the Redmine Knowledgebase plugin.

The source code is available on GitHub at https://github.com/alexbevi/redmine_knowledgebase and is free to view, modify, and use.

For more information on these generators, the source is available at /path/to/redmine/lib/generators. For additional information about Ruby on Rails generators, see http://guides.rubyonrails.org/generators.html.

In order to create our knowledgebase plugin, we'll first run the redmine_plugin generator, which creates the bare minimum folder structure and files we'll need to get started. This is done as follows:

$ rails generate redmine_plugin redmine_knowledgebase
  create  plugins/redmine_knowledgebase/app
  create  plugins/redmine_knowledgebase/app/controllers
  create  plugins/redmine_knowledgebase/app/helpers
  create  plugins/redmine_knowledgebase/app/models
  create  plugins/redmine_knowledgebase/app/views
  create  plugins/redmine_knowledgebase/db/migrate
  create  plugins/redmine_knowledgebase/lib/tasks
  create  plugins/redmine_knowledgebase/assets/images
  create  plugins/redmine_knowledgebase/assets/javascripts
  create  plugins/redmine_knowledgebase/assets/stylesheets
  create  plugins/redmine_knowledgebase/config/locales
  create  plugins/redmine_knowledgebase/test
  create  plugins/redmine_knowledgebase/test/fixtures
  create  plugins/redmine_knowledgebase/test/unit
  create  plugins/redmine_knowledgebase/test/functional
  create  plugins/redmine_knowledgebase/test/integration
  create  plugins/redmine_knowledgebase/README.rdoc
  create  plugins/redmine_knowledgebase/init.rb
  create  plugins/redmine_knowledgebase/config/routes.rb
  create  plugins/redmine_knowledgebase/config/locales/en.yml
  create  plugins/redmine_knowledgebase/test/test_helper.rb

As Redmine's plugin system is inspired by the Rails Engines plugin, they can also be considered as miniature applications that provide functionality to the host (Redmine) application.

Additional information regarding the Redmine plugin internals is available at http://www.redmine.org/projects/redmine/wiki/Plugin_Internals.

Note

When the plugin system was first introduced, Redmine plugins were effectively Rails Engines, but this is no longer the case (http://www.redmine.org/issues/10813).

The plugin skeleton that the Redmine plugin generator has produced includes placeholders for a number of features we'll want to include later, such as tests, initialization, documentation, MVC, database migrations, and localization.

Using custom gemsets in our plugin

As Redmine is a Ruby on Rails application, all external dependencies are managed using Bundler. This utility greatly simplifies dependency management, but by default only allows a single Gemfile to be evaluated when a bundle is being installed.

Although not provided by the default plugin generator, if our plugin will require external gemsets, we can add a Gemfile to our plugin root, which will be automatically merged by Redmine whenever Bundler commands are executed or dependencies are evaluated.

For example, we can create Gemfile in our plugin root directory as follows:

source 'https://rubygems.org'

gem 'redmine_acts_as_taggable_on', '~> 1.0'
gem 'ya2yaml'

When the Bundler installation command is run from the root of our Redmine installation, our plugin's custom gems will be included and installed:

$ bundle install
Using rake (10.1.1)
...
Using redmine_acts_as_taggable_on (1.0.0)
Using rmagick (2.13.2)
Using sqlite3 (1.3.8)
Using ya2yaml (0.31)
Using yard (0.8.7.3)
Your bundle is complete!

Generating models and controllers

The generators introduced previously include variants to generate a plugin's models and controllers.

One of the primary features of our knowledgebase plugin is the ability to manage categories. In order to implement this feature, we'll first have to generate the necessary model, migration, and controller code.

Redmine's plugin model generator parameters are the plugin name, the name of the model, then a list of attributes, and their data types:

$ rails generate redmine_plugin_model redmine_knowledgebase Category title:string description:text
  create  plugins/redmine_knowledgebase/app/models/category.rb
  create  plugins/redmine_knowledgebase/test/unit/category_test.rb
  create  plugins/redmine_knowledgebase/db/migrate/001_create_categories.rb

As we've provided some field details in our generator, the generated migration will be populated accordingly. The same process can be followed to generate the controller that coincides with our model.

Redmine's plugin controller generator follows the same pattern as the plugin model generator, but doesn't require field details:

$ rails generate redmine_plugin_controller redmine_knowledgebase Category
  create  plugins/redmine_knowledgebase/app/controllers/category_controller.rb
  create  plugins/redmine_knowledgebase/app/helpers/category_helper.rb
  create  plugins/redmine_knowledgebase/test/functional/category_controller_test.rb

Redmine's plugin views cannot be directly generated, but as they follow the standard Rails layout convention of extending ActionController and ActionView (http://guides.rubyonrails.org/layouts_and_rendering.html), we can quickly add view templates and partials to our plugin by placing the necessary files under /path/to/redmine/plugins/redmine_knowledgebase/app/views.

Note

Some of the naming conventions used by the plugin generators at the time of writing this book don't match the Ruby on Rails naming conventions. Database migrations should be prefixed with a timestamp, not an incremental value, and category_controller would become categories_controller.

The preceding examples were left intact as they reflect what the actual Redmine plugin generators produce.

 

Diving into the initialization file


Every Redmine plugin requires an initialization file (init.rb) to be included in order for the plugin to be registered with Redmine upon startup.

A stripped down version of the initialization file we'll be working on is included in the following snippet to highlight some of the attributes and helpers that are available:

Redmine::Plugin.register :redmine_knowledgebase do
  name        'Knowledgebase'
  author      'Alex Bevilacqua'
  author_url  'http://www.alexbevi.com'
  description 'a knowledgebase plugin for Redmine'
  url         'https://github.com/alexbevi/redmine_knowledgebase'
  version     ' 3.0.0'

  requires_redmine :version_or_higher => '2.0.0'
  
  settings :default => {
    :sort_category_tree => true,
    :show_category_totals => true,
    :summary_limit => 5,
    :disable_article_summaries => false
  }, :partial => 'settings/knowledgebase_settings'

  project_module :knowledgebase do
    permission :view_articles, {
      :knowledgebase => :index,
      :articles      => [:show, :tagged],
      :categories    => [:index, :show]
    }
    permission :create_articles, {
      :knowledgebase => :index,
      :articles      => [:show, :tagged, :new, :create, :preview],
      :categories    => [:index, :show]
    }
    # ...
  end
end

This plugin registration block contains field definitions that are used to identify the plugin to Redmine.

Note

As of Redmine 2.3.3, based on the identifier with which the plugin was registered (:redmine_knowledebase in this case), the plugin would have to reside in /path/to/redmine/plugins/redmine_knowledgebase in order to be detected properly. Note that this can be overridden using a directory attribute in future versions of Redmine, as per http://www.redmine.org/issues/13927.

Plugin attributes

The values of these fields are used to either identify the plugin to the administrator when they visit the plugin list at http://localhost:3000/admin/plugins of their Redmine deployment, or to provide some assignment or initialization functionality.

Tip

Ruby on Rails application default to port 3000 when run locally. As this is standard, we'll be using http://localhost:3000 as the base URL for all Redmine links.

The attributes that can be provided to the Redmine::Plugin.register block are as follows:

  • name: This is the full name of the plugin.

  • description: This gives a brief description of what the plugin does.

  • url: This is the website of the plugin itself. This is generally the online repository URL (GitHub, Bitbucket, Google Code, and so on), or plugin website (if available or applicable).

  • author: This holds the name(s) of the author(s) of the plugin.

  • author_url: This is generally the link to either the author(s)' e-mail addresses or blogs.

  • version: This is the internal version number of the plugin. Though not required, it is a good practice to use Semantic Versioning (see http://semver.org for more information), as Redmine follows a similar (though not official) numbering scheme.

  • settings: This field is used to define and set the default values of internal plugin settings and link to a view partial, which system administrators can use to set plugin configuration values.

    settings :default => {
        :sort_category_tree => true,
      }, :partial => 'settings/knowledgebase_settings' 

The preceding example lets our plugin know that we will be providing a configuration partial, as well as initializing a custom settings value of sort_category_tree to true.

As Redmine plugins follow the standard Ruby on Rails application hierarchy, the implied location of our settings partial would be /path/to/redmine/plugins/redmine_knowledgebase/app/views/settings/_knowledgebase_settings.html.erb.

Settings management will be covered in more detail in Chapter 7, Managing Plugin Settings.

Initialization checks

Redmine provides a number of helper functions that can be used to assist plugin authors ensuring compatibility with different versions of Redmine, as well as other plugins.

Checking for a specific Redmine version

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:

  • Exact match

    requires_redmine "2.3.3"
    requires_redmine :version => "2.3.3"
  • Exact match of more than one version

    requires_redmine :version => ["2.2.0", "2.3.0"]
  • Match a specific version and revision

    requires_redmine "2.3"
    requires_redmine :version => "2.3"
  • Minimum version or higher

    requires_redmine :version_or_higher => "2.3.3"
  • Range of versions

    requires_redmine :version => "2.2.0".."2.3.0"
    requires_redmine :version => "2.2".."2.3"

Ensuring the existence of other plugins

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:

  • Exact match

    requires_redmine_plugin :sample_plugin :version => "1.0.0"
    requires_redmine_plugin :sample_plugin "1.0.0"
  • Minimum version or higher

    requires_redmine_plugin :sample_plugin :version_or_higher => "1.0.0"
  • Range of versions

    requires_redmine_plugin :sample_plugin :version => ["0.1.0", "0.2.0"]

Extending core Redmine features

Now that we've initialized our plugin with some basic details and requirements, we can start integrating directly with Redmine.

A number of helper methods are available to plugin authors, which facilitate this integration with core components, such as menus and permissions.

Working with Redmine menus

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:

  • :param: This is the parameter key that will be used as the project ID (the default is :id).

  • :if: This is a proc that prevents the menu from rendering unless it is evaluated to true.

  • :caption: This is the menu caption (label), which can be a localized symbol, proc, or string.

  • :before or :after: This is used to position the menu entry relative to an existing entry. For example, :after => :activity, or :before => :issues.

  • :first or :last: If either of these options is set to true, the menu item will be placed at the absolute beginning or end of the target menu.

  • :html: This is a hash of HTML options that will be passed to the link_to instance that is used to render the menu item.

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.

Initializing named permissions

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:

  • :public: This changes the permission to public if set to true (implicitly given to any user)

  • :require: This can be set to either :loggedin or :member, and is used to further restrict the types of users the permission can be applied to

  • :read: This is set to true so that the permission is still granted on closed projects

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

Project module availability

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

Adding custom events to the activity stream

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.

Registering custom text formatting macros

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.

 

Summary


We now have a better understanding of what options are available to us when setting up a plugin for use with Redmine.

In this chapter, we covered the various plugin attributes that can be used to identify the plugin to Redmine. We also introduced some helper methods, which we'll be returning to throughout the book when we cover elements such as permissions, activity streams, and configuration in more detail.

In the next chapter, we will extend our knowledgebase plugin through the use of view hooks.

About the Author

  • Alex Bevilacqua

    Alex Bevilacqua is an advocate for open standards, as well as a passionate and enthusiastic open source developer with over 10 years of experience. He is skilled in Ruby, Python, C#, Flash, Flex, JavaScript, and others. He is the author of a number of Redmine extensions and plugins; two of the most popular being the Redmine Knowledgebase and the Redmine Dropbox Attachments plugin. He currently works for a leading digital marketing company in Toronto where he works on process automation, data collection, and aggregation initiatives. His personal blog can be found at http://www.alexbevi.com.

    Browse publications by this author

Latest Reviews

(2 reviews total)
Hello everybody ! I would like to say that the teaching material I was presenting is of a very good level for beginners and developers. I am very happy with the culture of Redmine and I think it can promote great transformations in the world of Project Management and tasks. Congratulations on your work. Carlos Miguel
Good

Recommended For You

Book Title
Unlock this full book with a FREE 10-day trial
Start Free Trial