Redmine Plugin Extension and Development (2014)
Preface
Imagine this: you stumble across a versatile open source project that outperforms most proprietary systems you've tested against, but it falls short due to just one simple yet critical missing feature. We've all been there before.
As hobbyists, developers, or just tinkerers, we dig into the code only to find that although the codebase is clean and well documented, we're not really sure where to start.
With Redmine, the answer to our dilemma is straightforward: write a plugin that fills this blank we've identified, allowing us to quickly implement feature x without having to hack the core system.
The Redmine authors have gone to great lengths to provide a plugin system that is extensive enough to allow even the most complex solutions to be quickly and efficiently implemented without having to resort to hacks.
This book will describe this plugin authorship process using an existing plugin that has been in production for a number of years as the basis for the various features we'll be implementing.
What this book covers
Chapter 1, Introduction to Redmine Plugins, provides an introduction to the basic structure of a Redmine plugin as well as some preliminary initialization and configuration settings.
Chapter 2, Extending Redmine Using Hooks, dives into how Redmine core components such as internal models, views, controllers, and helpers can be extended from within our plugin through the use of the hooks system.
Chapter 3, Permissions and Security, introduces the Redmine permissions system and how our plugin can make use of this existing infrastructure. It also includes a case study on how a custom access control system can be implemented by a plugin in order to limit access to content in a more granular fashion.
Chapter 4, Attaching Files to Models, highlights how quickly Redmine's built-in file attachment components can be added to our plugin models, views, and controllers.
Chapter 5, Making Models Searchable, walks the user through how some of Redmine's core plugins can be used to allow a plugin model's content to be included within the search system. It also covers how permissions are used to limit search results, and even how the default search functionality provided through Redmine's core plugin can be overridden, allowing us to further limit results using custom logic or permissions.
Chapter 6, Interacting with the Activity Stream, introduces another core Redmine plugin that allows us to inject custom events into a project's activity stream. It also covers how activity events are defined and formatted and how activity providers are configured and registered.
Chapter 7, Managing Plugin Settings, covers the definition and initialization of plugin settings and how a generic view partial can be provided to facilitate management of these settings values. It also discusses how these setting values can be applied within our plugin's views and controllers.
Chapter 8, Testing Your Plugin, provides an introduction to writing and running unit, integration, and functional tests that tie into Redmine's infrastructure. It also provides a brief note on how to integrate a GitHub hosted Redmine plugin with the Travis CI continuous integration service.
Appendix, Releasing Your Plugin, gives some pointers to plugin authors regarding what they can do to promote the release of their newly authored plugin. This is only meant to provide a handful of suggestions and not act as a de facto guide on plugin publication.
What you need for this book
In order to write plugins for Redmine, a working Ruby/Rails environment should be available, as well as a copy of Redmine.
Setting up Ruby is platform dependent, but we can get started relatively quickly. For instructions for Windows, visit http://rubyinstaller.org/. For OSX or Linux, visit either http://rvm.io/ or https://github.com/sstephenson/rbenv.
The Redmine source code can be downloaded at http://www.redmine.org or from GitHub at https://github.com/redmine/redmine.
If you've never set up Redmine yourself, a comprehensive guide is available at http://www.redmine.org/projects/redmine/wiki/RedmineInstall.
Who this book is for
The target audience of this book is anyone who has basic to intermediate experience with Ruby and is comfortable working with Ruby on Rails applications. These are the basic skills required to get Redmine up and running in a local environment, which is where most plugin development would be done.
Readers who are interested in writing Redmine plugins and do not possess these basic development skills are encouraged to investigate further as there are many excellent resources available online. Some suggestions are as follows:
· http://rubylearning.com/
· https://www.ruby-lang.org/en/documentation/quickstart/
· http://www.codecademy.com/tracks/ruby
· http://tryruby.org
Conventions
In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles and an explanation of their meaning.
Code words in text are shown as follows: "Project module permissions are declared almost identically but are contained within a project_module block."
A block of code is set as follows:
permission :access_global_knowledgebase, {
:knowledgebase => :index
}
When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:
permission :access_global_knowledgebase, {
:knowledgebase => :index
}
Any command-line input or output is written as follows:
permission(name, actions, options = {})
New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: "If we were to check the roles editor now by navigating to Administration | Roles and Permissions and select any role to edit, this new permission would in fact appear under the Project category."
Note
Warnings or important notes appear in a box like this.
Tip
Tips and tricks appear like this.