Plugin Tutorial » History » Version 3

« Previous - Version 3/103 (diff) - Next » - Current version
Jean-Philippe Lang, 2008-08-10 17:36


Plugin Tutorial

Creating a new Plugin

Open up a command prompt and "cd" to your redmine directory, then execute the following command:

% ruby script/generate redmine_plugin Pools

The plugin structure is created in vendor/plugins/redmine_pools:

      create  vendor/plugins/redmine_pools/app/controllers
      create  vendor/plugins/redmine_pools/app/helpers
      create  vendor/plugins/redmine_pools/app/models
      create  vendor/plugins/redmine_pools/app/views
      create  vendor/plugins/redmine_pools/db/migrate
      create  vendor/plugins/redmine_pools/lib/tasks
      create  vendor/plugins/redmine_pools/assets/images
      create  vendor/plugins/redmine_pools/assets/javascripts
      create  vendor/plugins/redmine_pools/assets/stylesheets
      create  vendor/plugins/redmine_pools/lang
      create  vendor/plugins/redmine_pools/README
      create  vendor/plugins/redmine_pools/init.rb
      create  vendor/plugins/redmine_pools/lang/en.yml

Edit vendor/plugins/redmine_pools/init.rb too adjust plugin information (name, author, description and version):

require 'redmine'

Redmine::Plugin.register :redmine_pools do
  name 'Pools plugin'
  author 'John Smith'
  description 'A plugin for managing pools'
  version '0.0.1'
end

Then restart the application and point your browser to http://localhost:3000/admin/info.
After logging in, you should see your new plugin in the plugins list:

Generating a controller

For now, the plugin doesn't do anything. So let's create a controller for our plugin.
Go back to the command prompt and run:

% ruby script/generate redmine_plugin_controller Pools pools index vote
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/pools
      create  test/functional/
      create  app/controllers/pools_controller.rb
      create  test/functional/pools_controller_test.rb
      create  app/helpers/pools_helper.rb
      create  app/views/pools/index.html.erb
      create  app/views/pools/vote.html.erb

A controller PoolsController with 2 actions (#index and #vote) is created.

Edit app/controllers/pools_controller.rb in redmine_pools directory to implement these 2 actions:

class PoolsController < ApplicationController
  unloadable

  @@pools = [ {:id => 1, :title => 'First pool', :question => 'This is the first pool question', :yes => 0, :no => 0},
              {:id => 2, :title => 'Second pool', :question => 'This is the second pool question', :yes => 0, :no => 0} ]

  def index
    @pools = @@pools
  end

  def vote
    pool = @@pools.find {|p| p[:id].to_s == params[:id]}
    # saves the vote
    pool[params[:answer].to_sym] += 1
    flash[:notice] = 'Vote saved.'
    redirect_to :action => 'index'
  end
end

Then edit app/views/pools/index.html.erb that will display existing pools:

<h2>Pools</h2>

<% @pools.each do |pool| %>
  <p>
  <%= pool[:question] %>?
  <%= link_to 'Yes', {:action => 'vote', :id => pool[:id], :answer => 'yes'}, :method => :post %> (<%= pool[:yes] %>) /
  <%= link_to 'No', {:action => 'vote', :id => pool[:id], :answer => 'no'}, :method => :post %> (<%= pool[:no] %>)
  </p>
<% end %>

You can remove vote.html.erb since no rendering is done by the corresponding action.

Now, restart the application and point your browser to http://localhost:3000/pools.
You should see the 2 pools and you should be able to vote for them.

plugins_list1.png (3.23 KB) Jean-Philippe Lang, 2008-08-08 20:33

pools1.png (16.5 KB) Jean-Philippe Lang, 2008-08-10 17:37

application_menu.png (9.22 KB) Jean-Philippe Lang, 2008-08-10 18:08

project_menu.png (7.26 KB) Jean-Philippe Lang, 2008-08-10 18:26

project_menu_pools.png (7.38 KB) Jean-Philippe Lang, 2008-08-10 18:38

permissions1.png (8.43 KB) Jean-Philippe Lang, 2008-08-10 19:10

modules.png (10 KB) Jean-Philippe Lang, 2008-08-10 19:36

project_menu.png (17.3 KB) Ric Turley, 2010-05-15 15:53

project_menu_pools.png (16.9 KB) Ric Turley, 2010-05-15 15:53

plugins_list1.png (4.37 KB) Jean-Philippe Lang, 2012-05-28 10:51

plugin_config_view.png (21.6 KB) Paul Kerr, 2013-02-01 19:13

plugin_with_config.png (24.3 KB) Paul Kerr, 2013-02-01 19:14