View hooks

The primary use of hooks in Redmine is to inject functionality into an existing view.

A view hook is executed while the HTML code of a view is being rendered.

View hooks are likely to be the most frequently used type of hook by plugin authors. Through these hooks, we can add functionality from our plugins to existing Redmine views and partials.

As an example, let's add the ability to associate knowledgebase articles with an issue. We'll implement this in a similar fashion to how issues can be associated with each other.

In order to display this association, we will extend the relevant issue views using view hooks. To accomplish this, the first step is to create a class that extends Redmine::Hook::ViewListener:

module RedmineKnowledgebase
  class Hooks < Redmine::Hook::ViewListener
    render_on :view_issues_show_description_bottom,
              :partial => 'redmine_knowledgebase/hooks/view_issues_show_description_bottom'
  end
end

This file will be saved to our plugin's lib folder as /path/to/redmine/plugins/redmine_knowledgebase/lib/hooks.rb.

To include the custom hook in our plugin, the hooks.rb file will simply need to be added to the plugin's init.rb file as a requirement.

The preceding hook implementation is done using the render_on helper method, which facilitates rendering a partial using the context.

In the following sample, we'll accomplish the same result by defining the callback method ourselves and manually configuring the context object:

module RedmineKnowledgebase
  class Hooks < Redmine::Hook::ViewListener
    def view_issues_show_description_bottom(context = {})
      # the controller parameter is part of the current params object
      # This will render the partial into a string and return it.
      context[:controller].send(:render_to_string, {
        :partial => " redmine_knowledgebase/hooks/view_issues_show_description_bottom",
        :locals => context
      })

      # Instead of the above statement, you could return any string generated
      # by your code. That string will be included into the view
    end
  end
end

When this hook is called and a callback has been registered, it will yield raw HTML code that will be inserted in the following issue form details:

In our example, we've added an Articles section to the issues of the current project. Note that the actual implementation code for this is not covered as it goes a bit out of the scope of this book.