Redmine

h1. Tutoriel du plugin Polls 

Remarque : Pour suivre ce tutoriel, vous devez avoir installé Redmine devel r1786 ou supérieur.

{{>toc}}

h2. Créer un nouveau plugin

Vous devez préalablement initialiser la variable RAILS_ENV sur "production" dans votre session shell pour continuer le tutotiel, pour ce faire, tapez :

<pre>

$ export RAILS_ENV="production"

</pre>

Pour créer un plugin Redmine, il existe des generateur pour les taches essentielles. 

La syntaxe des générateurs est :

<pre>ruby script/generate redmine_plugin <plugin_name></pre>

pour commencer, on va se positionner dans le répertoire de l'application Rails Redmine, puis créer la structure du plugin :

  % ruby script/generate redmine_plugin Polls

La structure du plugin est créé dans le repertoire @vendor/plugins/redmine_polls@:

<pre>

      create  vendor/plugins/redmine_polls/app/controllers

      create  vendor/plugins/redmine_polls/app/helpers

      create  vendor/plugins/redmine_polls/app/models

      create  vendor/plugins/redmine_polls/app/views

      create  vendor/plugins/redmine_polls/db/migrate

      create  vendor/plugins/redmine_polls/lib/tasks

      create  vendor/plugins/redmine_polls/assets/images

      create  vendor/plugins/redmine_polls/assets/javascripts

      create  vendor/plugins/redmine_polls/assets/stylesheets

      create  vendor/plugins/redmine_polls/lang

      create  vendor/plugins/redmine_polls/README

      create  vendor/plugins/redmine_polls/init.rb

      create  vendor/plugins/redmine_polls/lang/en.yml

</pre>

Editer @vendor/plugins/redmine_polls/init.rb@ pour adjuster les informations (attributs) du plugin (nom, auteur, description et version):

<pre><code class="ruby">

require 'redmine'

Redmine::Plugin.register :redmine_polls do

  name 'Polls plugin'

  author 'John Smith'

  description 'A plugin for managing polls'

  version '0.0.1'

end

</code></pre>

Redemarrez l'application Redmine et ouvrez un navigateur sur l'URL http://localhost:3000/admin/plugins.

Après vous être loggué avec les droits d'administrateur Redmine, vous devriez voir la liste des plugins tel que :

!plugins_list1.png!

h2. Générer un modèle Rails de plugin Redmine

pour le moment le plugin ne persiste aucuns résultats

Nous allons donc créer un modèle Poll simple, tel que :

<pre>

   ruby script/generate redmine_plugin_model <plugin_name> <model_name> [<fields>]

</pre>

La commande exacte pour notre cas sera :

<pre>

   ruby script/generate redmine_plugin_model polls poll question:string yes:integer no:integer

</pre>

cette commande crée le modèle Rails Poll et les fichiers de migration correspondant

*Remarque : Il est possible que vous deviez renommer les fichiers de migration, les migrations avec des timestamps ne sont pas supportée par le moteur Redmine Actuelle, Si les migrations portent une numérotation avec des timestamps, renommez-les avec "001" "002", etc... 

   <pre>cd vendor/plugins/redmine_polls/db/migrate

mv  20091009211553_create_polls.rb 001_create_polls.rb

cd ../../../../..</pre>

Si vous avez déja executé une migration, vous devez mettre à jour les informations dans la table plugin_schema_info en adequation avec la nouvelle numérotation.

Migrer la base de données avec la commande :

  rake db:migrate_plugins

Il est à noter que chaque plugin à son propre jeux de migration.

Nous allons ajouter des Votes via la console rails pour pouvoir faire des tests avec.

La console Rails permet l'ajout interactif d'enregistrement sur les modèles rails, c'est une shell Ruby Irb, qui pré-charge l'environnement de l'application rails depuis laquelle il est lancé.

Pour le moment nous allons juste créer un objet Poll

<pre>

script/console

>> Poll.create(:question => "Pouvez-vous voir ce vote ?")

>> Poll.create(:question => "Pouvez-vous voir cet autre vote ?")

>> exit

</pre>

Editez @vendor/plugins/redmine_polls/app/models/poll.rb@ dans le répertoire de votre plugin et ajoutez une méthode #vote qui sera appelée par votre controller:

<pre><code class="ruby">

class Poll < ActiveRecord::Base

  def vote(answer)

    increment(answer == 'yes' ? :yes : :no)

  end

end

</code></pre>

h2. Generer un controller

Pour le moment le plugins ne fait rien, donc nous allons créer un controller Rails pour celui-ci.

Nous pouvons utiliser le générateur Redmine prévue à cet effet :

<pre>ruby script/generate redmine_plugin_controller <plugin_name> <controller_name> [<actions>]</pre>

la commande exacte pour notre cas est :

<pre>

% ruby script/generate redmine_plugin_controller Polls polls index vote

      exists  app/controllers/

      exists  app/helpers/

      create  app/views/polls

      create  test/functional/

      create  app/controllers/polls_controller.rb

      create  test/functional/polls_controller_test.rb

      create  app/helpers/polls_helper.rb

      create  app/views/polls/index.html.erb

      create  app/views/polls/vote.html.erb

</pre>

un controlleur Rails  @PollsController@ avec 2 actions (@#index@ et @#vote@) vient d'être créé.

Editez @vendor/plugins/redmine_polls/app/controllers/polls_controller.rb@ dans le répertoire @redmine_polls@ pour implémenter ces deux actions.

<pre><code class="ruby">

class PollsController < ApplicationController

  unloadable

  def index

    @polls = Poll.find(:all)

  end

  def vote

    poll = Poll.find(params[:id])

    poll.vote(params[:answer])

    if poll.save

      flash[:notice] = 'Vote saved.'

      redirect_to :action => 'index'

    end

  end

end

</code></pre>

Ensuite, editez la vue @vendor/plugins/redmine_polls/app/views/polls/index.html.erb@ qui va afficher les votes existants.

<pre>

<h2>Polls</h2>

<% @polls.each do |poll| %>

  <p>

  <%= 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] %>)

  </p>

<% end %>

</pre>

Vous pouvez supprimer la vue @vendor/plugins/redmine_polls/app/views/polls/vote.html.erb@ comme il n'y a pas de rendu pour l'action correspondante.

Redemarreez le serveur Rails de Redmine et ouvrez votre navigateur sur l'URL http://localhost:3000/polls.

Vous devriez voir deux votes et vous pouvez les essailler : 

!pools1.png!

Remarque : les resultats des votes sont remis à zero à chaque requête si vous ne lancez pas votre application en environnement "production", vue que le modèle Poll est stocké dans une variable de classe dans notre exemple. 

h2. Traductions

L'emplacement des fichiers YAML d'internationalisation peut varier en fonction de votre version de Redmine :

|_. Version |_. Path|

| < 0.9 | @.../redmine_polls/lang@ |

| >= 0.9 | @.../redmine_polls/config/locales@ |

Si vous voulez que votre plugin marche dans les deux cas vous devez ajouter les fichiers dans les deux cas au bon format.

h2. Gestion des menus

Notre controller marche bien, mais nos utilisateurs n'en connaissent pas l'existence, il faut donc utilser l'API Redmine pour etendre les menus

Nous allons ajouter un onglet au menu Application

So let's add a new item to the application menu.

h3. Gestion du menu application

Editez le fichier @vendor/plugins/redmine_polls/init.rb@ à la racine de votre plugin et ajoutez la ligne suivante dans le bloc ""registration"" :

<pre><code class="ruby">

Redmine::Plugin.register :redmine_polls do

  [...]

  menu :application_menu, :polls, { :controller => 'polls', :action => 'index' }, :caption => 'Polls'

end

</code></pre>

la syntaxe est :

  menu(menu_name, item_name, url, options={})

Il y a cinq menu dans Redmine que vous pouvez étendre :

* @:top_menu@ - le menu en haut à gauche

* @:account_menu@ - le menu en haut à droite avec la gestion des comptes et connexions

* @:application_menu@ - Le menu affiché quand un utilisateur n'est dans aucuns projets.

* @:project_menu@ - Le menu affiché quand un utilisateur est dans un projet.

* @:admin_menu@ - le menu d'administration 

les options disponibles sont :

* @:param@ - la clef parametre utilisée pour les id de projet (valeur par défaut @:id@)

* @:if@ - un Proc appelé avant de faire le rendu du menu,l'item est affiché que si le Proc retourne true

* @:caption@ - Le label du menu du type:

  * un symbole de chaine de caratères localisée

  * une chaine de caratères

  * un Proc qui peut pendre le project_id en argument

* @:before@, @:after@ - specifie ou l'item du menu doit être inséré (ex. @:after => :activity@)

* @:first@, @:last@ - si ils sont true, l'item est positionné au début ou a la fin du menu (ex. @:last => true@)

* @:html@ - un hachage d'options html passés à @link_to@ pour le rendu du menuitem

Dans notre exemple, nous avons ajoutez un item au menu application, qui est vide par defaut.

Redemarrez l'application et allez à l'URL http://localhost:3000:

!application_menu.png!

Maintenant vous pouvez accéder aux votes en cliquant sur l'onglet Polls depuis l'ecran d'accueil de Redmine

h3. Etendre le menu projet

On va considérer, mantenant que les votes sont définis au niveau des projets (même si ce n'est pas le cas dans le modèle de notre exemple)

Donc, on veut ajouter l'onglet au menu Projet et plus au menu Application.

Editez le fichier @init.rb@ et replacez la dernière ligne que nous avons ajoutez par les deux lignes suivantes :

<pre><code class="ruby">

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

end

</code></pre>

la deuxième ligne ajoute l'onglet Polls dans le menu Projet juste derrière l'onglet Activité.

la première ligne sert à déclarer que nos deux actions du @PollsController@ sont publiques.

Nous reviendrons plus tard sur les permissions.

Redémarrez encore l'application et entrez dans un de vos projets:

!http://www.redmine.org/attachments/3773/project_menu.png!

If you click the Polls tab, you should notice that the project menu is no longer displayed.

To make the project menu visible, you have to initialize the controller's instance variable @@project@.

Si vous cliquez sur l'onglet Polls, vous constatez que le menu projet n'est plus affiché.

Pour continuer à l'afficher, nous devons initialiser la variable d'instance @@project@ du controlleur.

Editez votre PollsController tel que:

<pre><code class="ruby">

def index

  @project = Project.find(params[:project_id])

  @polls = Poll.find(:all) # @project.polls

end

</code></pre>

L'id du projet est disponible dans @:project_id@ grace à l'option @:param => :project_id@ dans la déclaration du menu item précédante.

Maintenant, vous devriez continuer à voir le menu projet quand vous visualisez un vote :

!http://www.redmine.org/attachments/3774/project_menu_pools.png!

h2. Ajouter des nouvelles permissions

Pour le moment, tout le monde peut voter.

On peut rendre ceci configurable en ajoutant des permissions Redmine.

Nous allons definir deux permissions au niveau Projet, une pour visualiser et une pour voter.

Ces permissions ne seront donc plus publiques (l'option @:public => true@ disparait)

Editez @vendor/plugins/redmine_polls/init.rb@ pour remplacer la permission précedante avec les deux lignes suivantes :

<pre><code class="ruby">

  permission :view_polls, :polls => :index

  permission :vote_polls, :polls => :vote

</code></pre>

Redemarrez l'application et allez à l'URL http://localhost:3000/roles/report:

!permissions1.png!

on voit donc deux permissions de plus ajoutable à votre role.

Biensur, il va falloir ajouter du code au PollsController, donc ces actions sont pour le moment protégé par les permissions de l'utilisateur courant.

Pour cela, nous avons juste à ajouter le filtre @:authorize@ et faire en sorte que la variable d'instance @project est initialisée avant d'appeler ce filtre  

Voici à quoi ça doit ressembler dans l'action @#index@ :

<pre><code class="ruby">

class PollsController < ApplicationController

  unloadable

  before_filter :find_project, :authorize, :only => :index

  [...]

  def index

    @polls = Poll.find(:all) # @project.polls

  end

  [...]

  private

  def find_project

    # @project variable must be set before calling the authorize filter

    @project = Project.find(params[:project_id])

  end

end

</code></pre>

Récupérer le projet courant avant le @#vote@ peut-être fait de façon très similaire.

Après ça, voir un vote et voter ne sera accessible qu'aux administrateur ou aux utilisateurs que on un rôle approprié dnas le projet.

Pour traduire les symboles de vos permissions dans plusieurs langues, vous devez ajouter les labels de textes necessaires dans vos fichiers de langues tel que :

labels like this:

<pre><code class="ruby">

  permission_view_polls: Voir les votes

  permission_vote_polls: Voter

</code></pre>

Dans cette exemple, on a créé le fichier fr.yml, mais on peut créer des fichiers pour toutes les langues que l'on souhaite.

On voit dans cette exemple, que le lable est le symbole de la permission @:view_polls@ et @:vote_polls@ préfixé de @permission_@

Redemarrez votre application et pointer sur la section permissions.

h2. Créer un module de projets

Pour le moment, la fonctionnalité de vote est ajoutée à tous vos projets, mais on souhaite la rendre activable ou désactivable pour chaque projet.

On va donc créer un module de projet 'Polls'.

On fait ceci en inclant les permissions dans un bloc @#project_module@.

Editez @init.rb@ et changez la déclaration des permissions :

<pre><code class="ruby">

  project_module :polls do

    permission :view_polls, :polls => :index

    permission :vote_polls, :polls => :vote

  end

</code></pre>

Redemarrez votre application et pointer sur un de vos projet dans sa configuration.

Cliquez sur l'onglet Modules, vous y verez le module Polls à la fin de la liste de modules, désactivé par defaut.

!modules.png!

Vous pouvez l'activer ou le désactiver pour chaque projet. 

h2. Améliorer la vue du plugin

h3. Ajouter des Styles CSS

On va commencer par ajouter un CSS à notre vue 

Créez un fichier nommé @voting.css@ dans le répertoire @vendor/plugins/redmine_polls/assets/stylesheets@ :

<pre>

a.vote { font-size: 120%; }

a.vote.yes { color: green; }

a.vote.no  { color: red; }

</pre>

Quand on redemarrer l'application, les plugin assets sont copié dans @public/plugin_assets/redmine_polls/@

par le moteur de Rails pour les rendrent disponibles via votre serveur Web.

Donc toute modification des CSS des plugins impliques un redemarrage de Rails.

Ensuite, on va devoir ajouter les lignes suivantes dans la vue @vendor/plugins/redmine_polls/app/views/polls/index.html.erb@ pour que nos CSS soient pris en compte et incluent dans le header de cette vue par Redmine :

<pre>

<% content_for :header_tags do %>

    <%= stylesheet_link_tag 'voting', :plugin => 'redmine_polls' %>

<% end %>

</pre>

Notez que l'option @:plugin => 'redmine_polls'@ est requise quand on appelle le helper @stylesheet_link_tag@.

Les Javascripts peuvent être inclut dans le plugin en utilisant le helper @javascript_include_tag@ de la même manière.

h3. Modifier le titre de la page

on peut modifier le titre HTML de la page depuis le vue elle-même grace au helper @html_title@ 

Exemple:

  <% html_title "Polls" -%>

h2. Tester votre plugin

h3. test/test_helper.rb:

Voici le contenu de mon fichier de tests :

<pre>

require File.expand_path(File.dirname(__FILE__) + '/../../../../test/test_helper')

</pre>

h3. Exemple de test:

Contenu de requirements_controller_test.rb:

<pre>

require File.dirname(__FILE__) + '/../test_helper'

require 'requirements_controller'

class RequirementsControllerTest < ActionController::TestCase

  fixtures :projects, :versions, :users, :roles, :members, :member_roles, :issues, :journals, :journal_details,

           :trackers, :projects_trackers, :issue_statuses, :enabled_modules, :enumerations, :boards, :messages,

           :attachments, :custom_fields, :custom_values, :time_entries

  def setup

    @skill = Skill.new(:skill_name => 'Java')

    @project = Project.find(1)

    @request    = ActionController::TestRequest.new

    @response   = ActionController::TestResponse.new

    User.current = nil

  end

  def test_routing

    assert_routing(

      {:method => :get, :path => '/requirements'},

      :controller => 'requirements', :action => 'index'

    )

  end

</pre>

h3. Initialisation de la base de test :

Il semble plus facile d'initialiser la base de tests directement par la commande rake :

<pre>

rake db:drop db:create db:migrate db:migrate_plugins redmine:load_default_data RAILS_ENV=test

</pre>

h3. Executer les tests:

Pour executer the requirements_controller_test.rb on utilise la commande suivante :

<pre>

rake test:engines:all PLUGIN=redmine_requirements

</pre>

h3. Tester avec des utilisateurs et des projets 

If your plugin requires membership to a project, add the following to the beginning of your functional tests:

Si votre plugin requière de appartenances à un projet, ajouter les lignes suivantes pour que ce soit opérationnel :

<pre>

def setup

  @request    = ActionController::TestRequest.new

  @response   = ActionController::TestResponse.new

  User.current = nil

end

def test_index

  @request.session[:user_id] = 2

  get :index, :project_id => 1

  assert_response :success

  assert_template :index

end

</pre>