diff --git a/Plugin Tutorial.textile b/Plugin Tutorial.textile index 359172def..8bcb3b234 100644 --- a/Plugin Tutorial.textile +++ b/Plugin Tutorial.textile @@ -1,12 +1,11 @@ h1. Plugin Tutorial -This tutorial is based on Redmine 2.x. You can view a previous version of this tutorial for Redmine 1.x "here":/projects/redmine/wiki/Plugin_Tutorial?version=66. -It assumes that you're familiar with the Ruby on Rails framework. - -h3. NOTE: Redmine 3.x (Rails 4) script +This tutorial is based on Redmine 4.x and 3.x. +You can view a previous version of this tutorial. +"Redmine 1.x":/projects/redmine/wiki/Plugin_Tutorial?version=66 +"Redmine 2.x":/projects/redmine/wiki/Plugin_Tutorial?version=104 -This wiki uses @ruby script/rails@ on Redmine 2.x (Rails 3). -You need to use @ruby bin/rails@ or @rails@ on Redmine 3.x (Rails 4). +It assumes that you're familiar with the Ruby on Rails framework. {{>toc}} @@ -27,12 +26,12 @@ $ set RAILS_ENV=production Creating a new plugin can be done using the Redmine plugin generator. Syntax for this generator is: -
bundle exec ruby bin/rails generate redmine_plugin+
bundle exec rails generate redmine_pluginSo open up a command prompt and "cd" to your redmine directory, then execute the following command:
-$ bundle exec ruby script/rails generate redmine_plugin Polls +$ bundle exec rails generate redmine_plugin Polls create plugins/polls/app create plugins/polls/app/controllers create plugins/polls/app/helpers @@ -45,6 +44,11 @@ $ bundle exec ruby script/rails generate redmine_plugin Polls create plugins/polls/assets/stylesheets create plugins/polls/config/locales create plugins/polls/test + create plugins/polls/test/fixtures + create plugins/polls/test/unit + create plugins/polls/test/functional + create plugins/polls/test/integration + create plugins/polls/test/system create plugins/polls/README.rdoc create plugins/polls/init.rb create plugins/polls/config/routes.rb @@ -57,9 +61,11 @@ The plugin structure is created in @plugins/polls@. Edit @plugins/polls/init.rb@@@ -249,16 +256,16 @@ Available options are: * a String * a Proc that can take the project as argument -* @:before@, @:after@ - specify where the menu item should be inserted (eg. @:after => :activity@) -* @:first@, @:last@ - if set to true, the item will stay at the beginning/end of the menu (eg. @:last => true@) +* @:before@, @:after@ - specify where the menu item should be inserted (eg. @after: :activity@) +* @:first@, @:last@ - if set to true, the item will stay at the beginning/end of the menu (eg. @last: true@) * @:html@ - a hash of html options that are passed to @link_to@ when rendering the menu item In our example, we've added an item to the application menu which is empty by default. -Restart the application and go to http://localhost:3000: +Restart the application and go to http://localhost:3000/projects: p=. !application_menu.png! -Now you can access the polls by clicking the Polls tab from the welcome screen. +Now you can access the polls by clicking the Polls tab that appears when the user is not inside a project. h3. Extending the project menu @@ -269,8 +276,8 @@ Open @init.rb@ and replace the line that was added just before with these 2 line Redmine::Plugin.register :redmine_polls do [...] - permission :polls, { :polls => [:index, :vote] }, :public => true - menu :project_menu, :polls, { :controller => 'polls', :action => 'index' }, :caption => 'Polls', :after => :activity, :param => :project_id + permission :polls, { polls: [:index, :vote] }, public: true + menu :project_menu, :polls, { controller: 'polls', action: 'index' }, caption: 'Polls', after: :activity, param: :project_id end @@ -286,11 +293,11 @@ Edit your PollsController to do so:@@ -75,32 +81,34 @@ h2. Generating a model For now plugin doesn't store anything. Let's create a simple Poll model for our plugin. Syntax is:Redmine::Plugin.register :polls do name 'Polls plugin' - author 'John Smith' - description 'A plugin for managing polls' + author 'Author name' + description 'This is a plugin for Redmine' version '0.0.1' + url 'http://example.com/path/to/plugin' + author_url 'http://example.com/about' end
- bundle exec ruby script/rails generate redmine_plugin_modelSo, go to the command prompt and run:[field[:type][:index] field[:type][:index] ...] + bundle exec rails generate redmine_plugin_model [field[:type][:index] field[:type][:index] ...] -$ bundle exec ruby script/rails generate redmine_plugin_model polls poll question:string yes:integer no:integer +$ bundle exec rails generate redmine_plugin_model polls poll question:string yes:integer no:integer create plugins/polls/app/models/poll.rb create plugins/polls/test/unit/poll_test.rb - create plugins/polls/db/migrate/001_create_polls.rb + create plugins/polls/db/migrate/xxxxxxxxxxxx_create_polls.rb-This creates the Poll model and the corresponding migration file @001_create_polls.rb@ in @plugins/polls/db/migrate@: +This creates the Poll model and the corresponding migration file @xxxxxxxxxxxx_create_polls.rb@ in @plugins/polls/db/migrate@:+NOTE: For Redmine 3.x @class CreatePolls < ActiveRecord::Migration[5.2]@ is @class CreatePolls < ActiveRecord::Migration@. + You can adjust your migration file (eg. default values...) then migrate the database using the following command:-class CreatePolls < ActiveRecord::Migration +class CreatePolls < ActiveRecord::Migration[5.2] def change create_table :polls do |t| t.string :question - t.integer :yes, :default => 0 - t.integer :no, :default => 0 + t.integer :yes, default: 0 + t.integer :no, default: 0 end end end
@@ -118,10 +126,9 @@ Note that each plugin has its own set of migrations. Let's add some Polls in the console so we have something to work with. The console is where you can interactively work and examine the Redmine environment and is very informative to play around in. But for now we just need create two Poll objects@@ -195,8 +202,8 @@ h3. Adding routes Redmine does not provide the default wildcard route (@':controller/:action/:id'@). Plugins have to declare the routes they need in their proper @config/routes.rb@ file. So edit @plugins/polls/config/routes.rb@ to add the 2 routes for the 2 actions:-bundle exec ruby script/rails console -[rails 3] rails console ->> Poll.create(:question => "Can you see this poll") ->> Poll.create(:question => "And can you see this other poll") +bundle exec rails console +>> Poll.create(question: "Can you see this poll") +>> Poll.create(question: "And can you see this other poll") >> exit@@ -140,12 +147,12 @@ h2. Generating a controller For now, the plugin doesn't do anything. So let's create a controller for our plugin. We can use the plugin controller generator for that. Syntax is: -bundle exec ruby script/rails generate redmine_plugin_controller+[ ] bundle exec rails generate redmine_plugin_controllerSo go back to the command prompt and run:[ ] -$ bundle exec ruby script/rails generate redmine_plugin_controller Polls polls index vote +$ bundle exec rails generate redmine_plugin_controller Polls polls index vote create plugins/polls/app/controllers/polls_controller.rb create plugins/polls/app/helpers/polls_helper.rb create plugins/polls/test/functional/polls_controller_test.rb @@ -169,7 +176,7 @@ class PollsController < ApplicationController if poll.save flash[:notice] = 'Vote saved.' end - redirect_to :action => 'index' + redirect_to polls_path(project_id: params[:project_id]) end end@@ -181,9 +188,9 @@ Then edit @plugins/polls/app/views/polls/index.html.erb@ that will display exist <% @polls.each do |poll| %>- <%= poll.question %>? - <%= link_to 'Yes', { :action => 'vote', :id => poll[:id], :answer => 'yes' }, :method => :post %> (<%= poll.yes %>) / - <%= link_to 'No', { :action => 'vote', :id => poll[:id], :answer => 'no' }, :method => :post %> (<%= poll.no %>) + <%= poll.question %>? + <%= link_to 'Yes', { action: 'vote', id: poll[:id], answer: 'yes', project_id: @project }, method: :post %> <%= poll.yes %> / + <%= link_to 'No', { action: 'vote', id: poll[:id], answer: 'no', project_id: @project }, method: :post %> <%= poll.no %>
<% end %>You can find more information about Rails routes here: http://guides.rubyonrails.org/routing.html. @@ -223,7 +230,7 @@ Edit @plugins/polls/init.rb@ at the root of your plugin directory to add the fol Redmine::Plugin.register :redmine_polls do [...] - menu :application_menu, :polls, { :controller => 'polls', :action => 'index' }, :caption => 'Polls' + menu :application_menu, :polls, { controller: 'polls', action: 'index' }, caption: 'Polls' end-get 'polls', :to => 'polls#index' -post 'post/:id/vote', :to => 'polls#vote' +get 'polls', to: 'polls#index' +post 'post/:id/vote', to: 'polls#vote'
def index
@project = Project.find(params[:project_id])
- @polls = Poll.find(:all) # @project.polls
+ @polls = Poll.all # @project.polls
end
-The project id is available in the @:project_id@ param because of the @:param => :project_id@ option in the menu item declaration above.
+The project id is available in the @:project_id@ param because of the @param: :project_id@ option in the menu item declaration above.
Now, you should see the project menu when viewing the polls:
@@ -315,13 +322,13 @@ end
h2. Adding new permissions
For now, anyone can vote for polls. Let's make it more configurable by changing the permission declaration.
-We're going to declare 2 project based permissions, one for viewing the polls and an other one for voting. These permissions are no longer public (@:public => true@ option is removed).
+We're going to declare 2 project based permissions, one for viewing the polls and an other one for voting. These permissions are no longer public (@public: true@ option is removed).
Edit @plugins/polls/init.rb@ to replace the previous permission declaration with these 2 lines:
- permission :view_polls, :polls => :index
- permission :vote_polls, :polls => :vote
+ permission :view_polls, polls: :index
+ permission :vote_polls, polls: :vote
Restart the application and go to http://localhost:3000/roles/permissions:
@@ -336,12 +343,12 @@ Here is how it would look like for the @#index@ action:
class PollsController < ApplicationController
- before_filter :find_project, :authorize, :only => :index
+ before_action :find_project, :authorize, only: :index
[...]
def index
- @polls = Poll.find(:all) # @project.polls
+ @polls = Poll.all # @project.polls
end
[...]