I have always liked playing with plugins—not only as a user but also as a developer. I was amazed by the power that plugin APIs of some applications (for example, Apache HTTP server) give to let a developer extend their functionality. But when I started to learn the Redmine plugin API, I was amazed even more. Honestly, I can't say that I love Ruby on Rails or am a fan of it, but Redmine's plugin API (which is based on Ruby and Rails) is definitely the thing! Unlike other plugin APIs that I've seen before, it's not a regular plugin API. Thus, it embraces the Redmine API and the Rails API. And, it is based on Ruby, which is a very powerful metaprogramming language and provides unsurpassed means for patching code at runtime. As a result, this makes the Redmine plugin API nearly limitless—in other words, you can do almost anything with it.
While Redmine is quite featureful without plugins, you will most likely encounter a couple of them that you will want to make use of. However, this is where the first problem appears—it's not easy to find a working plugin for a certain version of Redmine. Also, the official list of plugins misses some their recent versions. Therefore, in this chapter, you will learn how to find plugins. Additionally, we will review some of them. But besides plugins, we will also pay some attention to Redmine themes, as a theme is what can help make an application look different.
So, who is this chapter for? In spite of what you might think, it's not only for administrators (who can install plugins) but also for other users who can use them (and, for example, ask an administrator to install some plugins).
In this chapter, we will cover the following topics:
- Finding plugins
- Installing a plugin
- A review of some plugins
- Themes
- A review of some themes
The official website of Redmine has a plugin directory, which you can use to find a plugin that you need (the directory, by the way, is implemented with another plugin that was written by Jean-Philippe Lang). However, many plugins on this list are not updated. For example, a plugin might be listed for an older Redmine, while its more recent version can actually be available. Also, more recent versions of some plugins can be available elsewhere, for example, on GitHub. (Sometimes, plugin authors, including me, fail to release updates for new versions of Redmine on time. So, volunteers can fork and update such plugins on GitHub.) Therefore, unfortunately, it is usually not enough to use the official directory to find a plugin for your version of Redmine.
Tip
A forum dedicated to plugins
In addition to the plugin directory, http://www.redmine.org/ has a forum that is dedicated to plugins. On it, you can discuss plugins, ask for help, request the development of a custom plugin, and so on. Check it out here:
Anyway, the official Redmine plugin directory should be your primary source of information about Redmine plugins. Yes, it's not ideal and not all plugins or their versions are registered there, but it was designed to maintain the list of plugins. Therefore, it has a legible structure, supports Redmine versions, allows us to filter plugins by a Redmine version, has a rating system, and so on.
This plugin directory can be accessed using http://www.redmine.org/plugins. Its start page is shown in the following screenshot:
The page that is shown in the preceding screenshot contains five recently registered plugins. On its sidebar, you can also see ten recently released versions (which include versions of plugins that were recently registered).
Below Latest plugins releases on the sidebar, you can see the top 10 best rated plugins. If you click on the Browse… link below it, you'll be redirected to a multi-page list of plugins (which we'll discuss later). This list will be sorted by ratings. In other words, using this link, you can quickly check out popular Redmine plugins.
You can also search for a plugin by entering related keywords in the Search box that is located in the top-right corner. However, it's important that you do this while being on the plugin list page! Alternatively, you can check the Redmine plugins checkbox in the search form, as shown in the following screenshot:
Finally, you can browse the plugin list by clicking on the Browse all Plugins... link that is located in the bottom-left corner. After you do so, you'll be redirected to the multi-page list where plugins are sorted alphabetically, as shown in the following screenshot:
Note this drop-down list in the top-right corner:
This select box can be used to filter plugins by a specific Redmine version. But remember that some plugin versions may be not registered in the official directory yet (you can try checking out the home page of the plugin or finding its forked version on GitHub, what is described in the very next subsection).
Finally, let's see what a plugin page looks like:
In the preceding screenshot, you can see only the upper part of the page. Usually, plugin pages contain a description of the plugin, which may include a couple of screenshots (so such pages are usually quite long).
Below the description, there is the Atom link. It can be used to subscribe to new versions of the plugin (and you should really do this if you use it). Also, the page lists all versions of the plugin, as shown on the following screenshot:
Below the Changelog section, you can find the User ratings section. It is shown in the following screenshot:
Redmine was written in Ruby on Rails, just like GitHub. GitHub is a project hosting and collaboration platform that is admired by open source developers mainly due to its social networking capabilities. Thus, even the code of Ruby on Rails is hosted there. For all these reasons, this great service is especially loved by "Rubists". Therefore, I guess it is not a surprise that most Redmine plugins can be found on GitHub.
In other words, GitHub can be a secondary source of information on Redmine plugins. So let's learn how we can find plugins there. To do this, we'll use the search form that is available at https://github.com/search
In this form, you should specify language:Ruby to make it search only for Ruby code and add keywords that describe the searched plugin along with the keyword Redmine.
By default, the search results will include only original repositories, that is, not forks (copies). Therefore, you may also need to search for a fork of the plugin that is compatible with the version of Redmine that you are using. So let's see how this can be done.
Tip
Limiting results by update date
You can restrict search results on GitHub by last push date using the pushed keyword. For example, use the language:Ruby Redmine pushed:>2015-02-19 fork:true query to find repositories that were modified after the release of Redmine 3.0.0, which happened on February 2, 2015. The fork:true condition is needed here as original repositories can remain unmodified for a longer time.
Thus, if you search for the Redmine Time Tracker plugin, which is believed to work only with Redmine 1.3.x according to the official plugin directory (at the time of writing this book), you will most likely find the repository of Fernando Kosh, as shown in this screenshot:
Unfortunately, the version of the plugin in this repository is for Redmine 2.4 and the last commit to it was made on April 11, 2014 (that's what I see at the time of writing this book). So, we need to find the most recently updated fork of this repository, that should theoretically support the most recent version of Redmine. To do this, we need to open the network graph, what can be done by clicking on the number of forks (141, as can be seen in the previous screenshot) on the search result page or the repository page. This is how this number is shown on the repository page:
Now, check out a sample of the network graph that is shown in the following screenshot:
On this graph, the spots are commits (that is, code changes). As we need to find the latest commit that was made to any of the forks shown in this graph, we drag it to the left (by clicking on it and moving the mouse arrow to the left-hand side) until we find the very rightmost spot.
When you hover your mouse arrow over a spot, a small box with brief information about the commit will be shown, as can be seen in the previous screenshot. This information will include the name of the author, the hash, and the commit message. In our case, the shown commit was made to support Redmine 3.2, and this is exactly what we need. So, it looks as if the repository of babky-atteq (Martin Babka) contains the searched version of the plugin. To move to this repository, just click on the spot.
Tip
On GitHub, forks are created by volunteers, who can make changes that are required by them or their organizations. So, the most recent commits do not automatically mean support for recent versions of Redmine. Therefore, you should always read commit messages to get an idea of what the changes are for. Also note that authors of forks are not necessarily good at programming (and so are authors of plugins though), so their forks can be buggy. Additionally, it's always a good idea to read the README.md file of the repository, which is shown on its start page, as this file can contain some information about the state of the code and known issues.