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:
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.
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.
To send us general feedback, simply send an e-mail to <feedback@packtpub.com> and mention the book title via the subject of your message.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the example code
This book continually references a sample plugin known as the Redmine Knowledgebase plugin.
This plugin is an actual production plugin that has been available since 2010 but has been continually refined by the author as well as multiple individual contributors.
The source code is MIT licensed and available at https://github.com/alexbevi/redmine_knowledgebase.
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the errata submission form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
Piracy
Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.
Please contact us at <copyright@packtpub.com> with a link to the suspected pirated material.
We appreciate your help in protecting our authors and our ability to bring you valuable content.
Questions
You can contact us at <questions@packtpub.com> if you are having a problem with any aspect of the book, and we will do our best to address it.
