I'm looking for a part-time remote job.

Hire me

I'm the author of:

Mastering Redmine is a comprehensive guide with tips, tricks and best practices, and an easy-to-learn structure.

Check the book's project or

Buy the book

Social pages of the book:

By buying this book you also donate to Redmine (see this page).

Follow me:

Using {{wiking_hook}} macro

In order to specify HTML code for custom hooks generated with the WikiNG plugin you need either to be familiar with writing basic Redmine plugins or to use the Hooks Manager plugin and be familiar with defining new placeholders for it... If you are not familiar with either you will find the {{wiking_hook}} macro useless.

In the following sections I will try to describe shortly how to handle hooks using these two methods:

Minimal plugin for handling custom hook

I did not test this code (wrote similar code many times so I believe it will work)! Please message me if it does not.

File structure

A plugin’s files should be located in <plugin-name> directory in #{RAILS_ROOT}/vendor/plugins. For example, if our plugin name is wiking_custom_hook the plugin’s directory should be #{RAILS_ROOT}/vendor/plugins/wiking_custom_hook.

The init.rb

Create a init.rb file in plugin’s directory:

require 'redmine'

require_dependency 'wiking_custom_hook'

RAILS_DEFAULT_LOGGER.info 'Starting WikiNG Custom Hook Plugin for Redmine'

Redmine::Plugin.register :wiking_custom_hook_plugin do
    name 'WikiNG Custom Hook'
    author 'Your Name'
    author_url 'http://your.homepage.com'
    description 'Plugin for handling WikiNG custom hooks.'
    url 'http://projects.andriylesyuk.com/projects/wiking/wiki/Using-hook-macro'
    version '0.0.1'

This is the entry file of the plugin.

Here is the description of some code elements:

  • wiking_custom_hook (in require_dependency 'wiking_custom_hook') is the name of another Ruby file (see below).
  • :wiking_custom_hook_plugin is the name of the plugin which should be equal to plugin's directory name plus _plugin.

The view listener

A hook can be handled by a Redmine::Hook::ViewListener instance. You need to create a derived class and put it into the lib subdirectory. The file of the class should be included into the init.rb this way: require_dependency '<class name>'.

In our case this file is lib/wiking_custom_hook.rb:

class WikingCustomHook < Redmine::Hook::ViewListener

    render_on :wiking_hook_custom_name, :partial => 'wiking/custom_name_hook'


Here is description of some code elements:

  • WikingCustomHook is the name of the class which should be "derived" from the file name (wiking_custom_hook without _ and with uppercase letters).
  • :wiking_hook_custom_name is the name of the hook (this particular hook should be specified in Wiki as !{{wiking_hook(custom_name)}}).
  • wiking/custom_name_hook is the path to the view file used to handle this hook (see below).

The view file

The view file should be located in the app/views directory. It is recommended to have a subdirectory which is wiking in our case. Our view file has name _custom_name_hook.rhtml... So its full path is app/views/wiking/_custom_name_hook.rhtml.

This is a partial view so it should start with _.
The content of the file is ERuby code (HTML + Ruby).

The WikiNG dynamic hooks support optional custom arguments and custom options which are available in a view file as args and options variables accordingly. For example, the code !{{wiking_hook(custom_name,custom,hook,wiking=1,name=hook)}} will make args and options contain:

  • args[0] = "custom";
  • args[1] = "hook";
  • options[:wiking] = "1";
  • options[:name] = "hook".

Also the following variables (not the full list) are available:

  • controller - an instance of ActionController
  • project - Redmine project object
  • request - The request object
  • page - Redmine Wiki page object

Adding support for custom hook to Hooks Manager

I did not test this code! Please message me if it does not work.
The Hooks Manager plugin provides a similar hook. See this page.

Describe the hook

Add the description of the hook to the config/placeholders.yml file of the Hooks Manager or WikiNG or, better, own small plugin:

  url: /projects/:project/wiki/:title
  outline: wiki
  page: :wiki
  location: :content

Here is the description of some properties:

  • wiking_hook_custom_name is the name of hook;
  • wiki is the path to outline file;
  • :wiki is the page name;
  • :content is the location name.

Specifying outline

Copy _wiki.rhtml from the app/views/placeholders directory of the Hooks Manager and modify it as follows:

<div class="hooks-top-menu"></div>
<div class="hooks-header"></div>
<div class="hooks-main">
  <div class="hooks-sidebar">
    <div class="hooks-box"></div>
  <div class="hooks-content">
    <div class="hooks-data" style="padding-top: 25px;">
    <% if hook == :view_wiki_inline_content || hook == :wiking_hook_custom_name %>
      <div id="hook-content"></div>
    <% end %>
<div class="hooks-footer"></div>

This file will be used to illustrate, where the hook is going to be placed.

For more details on registering new hooks in Hooks Manager check this page.
Terms of use | Privacy policy