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.