Using {{wiking_hook}} macro¶

• Using {{wiking_hook}} macro
  • Minimal plugin for handling custom hook
    • File structure
    • The init.rb
    • The view listener
    • The view file
  • Adding support for custom hook to Hooks Manager
    • Describe the hook
    • Specifying outline

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¶

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'
end

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'

end

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.

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¶

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:

wiking_hook_custom_name:
  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>
  <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>
  </div>
</div>
<div class="hooks-footer"></div>

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