Project

General

Profile

Plugin FAQ » History » Version 6

Mischa The Evil, 2020-08-26 06:48
Added an entry on 'requiring a certain Redmine plugin version'.

1 1 Jean-Baptiste Barth
h1. Frequently Asked Questions about Redmine plugins
2
3
{{toc}}
4
5
This page aims at documenting how to achieve simple things in Redmine plugins.
6
7
h2. Determine if a module is enabled
8
9
If your project is in the @@project@ variable: <pre><code class="ruby">
10
if @project.module_enabled?("<module_name>")
11
</code></pre>
12
13
First _modules_ are a project level concept. So be sure to make this check in an action that operates at project level. Redmine core generally uses a @before_filter@ called @find_project@ to find the current project in standard actions, which populates the @@project@ variable.
14
15
Available modules as of Redmine 2.3.x are: boards, calendar, documents, files, gantt, issue_tracking, news, repository, time_tracking, wiki. Each plugin can add its own module (see [[Plugin_Tutorial]] which adds a "polls" module).
16 2 Derric Atzrott
17
h2. Changing the layout of a page
18
19
Changing the layout of a page is done by overriding its View.  Redmine stores its views in @app/views/@.  To change a page's view using a plugin, first copy the view from @app/views/@ to @plugins/your_plugin/app/views/@ and then modify the file.
20
21
If multiple plugins override the same view, the last plugin loaded will be the one whose view is shown.  If you are having trouble finding out which view you need to override, check @config/routes.rb@ and look for a pattern that matches the URL for the page you are trying to modify.  That may help point you in the right direction.
22 3 Mischa The Evil
23
h2. Retrieve Redmine application configuration values
24
25
Redmine stores application configuration values in a file named @config/configuration.yml@. To retrieve (get) these configuration values from a plugin, Redmine provides the getter method @[]@, which is defined as a class method on @Redmine::Configuration@.
26
27
Example[1]:
28
29
Consider the following example configuration:
30
<pre><code class="yaml">
31
email_delivery:
32
    delivery_method: :smtp
33
    smtp_settings:
34
      address: "myaddress.com" 
35
      port: 25
36
      domain: "mydomain.com"
37
</code></pre>
38
39
Then the value of the @address@ configuration key can be retrieved by calling:
40
<pre><code class="ruby">Redmine::Configuration['email_delivery']['smtp_settings'][:address]</code></pre>
41
42
fn1. source: message#59809
43 4 Mischa The Evil
44
h2. Retrieve Redmine settings values
45
46
Redmine stores application settings values in the database. This includes any plugin settings. To interact (get/set) with these settings values from a plugin, Redmine automatically provides getter and setter methods in the form of @Setting.some_setting_name@ and @Setting.some_setting_name = "some value"@, for each setting on the @Setting@ model.
47
48
Examples:
49
50
* retrieve the value of the internal (Redmine core) 'welcome text' setting by calling:
51
<pre><code class="ruby">
52
Setting.welcome_text
53
</code></pre>
54
* retrieve the value of the 'notification_default' setting, as "provided" by the Polls plugin as documented in the [[Plugin Tutorial]], by calling:
55
<pre><code class="ruby">
56
Setting.plugin_polls['notification_default']
57
</code></pre>
58
59
It is not recommended to manually modify (set) settings values from a plugin. Instead, set these values via the provided UI's.
60 5 Mischa The Evil
61
h2. Require a certain Redmine version
62
63
Sometimes plugins require a specific feature implemented in the Redmine core or the plugin overrides a specific view which requires you to control on which (specific) versions of Redmine the plugin can be installed to assure that the required core is available. Such prevents a lot of issues regarding plugin-compatibility.
64
65
The above can be accomplished by utilizing the @requires_redmine@ method (see source:/trunk/lib/redmine/plugin.rb@19983#L227). Utilisation of the method provides an easy, reliable way to create plugins that require a specific version of Redmine and which are setup to stop Redmine with a message about a non-supported version if the version-requirement is not met.
66
67
{{collapse(View usage examples for requires_redmine method...)
68
<pre><code class="ruby">
69
# Requires Redmine 0.7.3 or higher
70
requires_redmine :version_or_higher => '0.7.3'
71
requires_redmine '0.7.3'
72
73
# Requires Redmine 0.7.x or higher
74
requires_redmine '0.7'
75
76
# Requires a specific Redmine version
77
requires_redmine :version => '0.7.3'              # 0.7.3 only
78
requires_redmine :version => '0.7'                # 0.7.x
79
requires_redmine :version => ['0.7.3', '0.8.0']   # 0.7.3 or 0.8.0
80
81
# Requires a Redmine version within a range
82
requires_redmine :version => '0.7.3'..'0.9.1'     # >= 0.7.3 and <= 0.9.1
83
requires_redmine :version => '0.7'..'0.9'         # >= 0.7.x and <= 0.9.x
84
</code></pre>
85
}}
86 6 Mischa The Evil
87
h2. Require a certain Redmine plugin version
88
89
Sometimes plugins require a specific feature implemented in another Redmine plugin or even a feature that is implemented in a specific version of another plugin which requires you to control dependencies on which the plugin relies before it can be installed to assure that the required plugin (version) is available. Such prevents a lot of issues regarding (inter) plugin-compatibility.
90
91
The above can be accomplished by utilizing the @requires_redmine_plugin@ method (see source:/trunk/lib/redmine/plugin.rb@19983#L274). Utilisation of the method provides an easy, reliable way to create plugins that require a specific version of Redmine and which are setup to stop Redmine with a message about a non-supported version if the version-requirement is not met.
92
93
{{collapse(View usage examples for requires_redmine_plugin method...)
94
<pre><code class="ruby">
95
# Requires a plugin named :foo version 0.7.3 or higher
96
requires_redmine_plugin :foo, :version_or_higher => '0.7.3'
97
requires_redmine_plugin :foo, '0.7.3'
98
99
# Requires a specific version of a Redmine plugin
100
requires_redmine_plugin :foo, :version => '0.7.3'              # 0.7.3 only
101
requires_redmine_plugin :foo, :version => ['0.7.3', '0.8.0']   # 0.7.3 or 0.8.0
102
</code></pre>
103
}}