Plugin FAQ » History » Version 7

Mischa The Evil, 2020-08-26 06:51
Slight adjustments to entry on 'requiring a certain Redmine plugin version'.

1 1 Jean-Baptiste Barth
h1. Frequently Asked Questions about Redmine plugins
2 1 Jean-Baptiste Barth
3 1 Jean-Baptiste Barth
{{toc}}
4 1 Jean-Baptiste Barth
5 1 Jean-Baptiste Barth
This page aims at documenting how to achieve simple things in Redmine plugins.
6 1 Jean-Baptiste Barth
7 1 Jean-Baptiste Barth
h2. Determine if a module is enabled
8 1 Jean-Baptiste Barth
9 1 Jean-Baptiste Barth
If your project is in the @@project@ variable: <pre><code class="ruby">
10 1 Jean-Baptiste Barth
if @project.module_enabled?("<module_name>")
11 1 Jean-Baptiste Barth
</code></pre>
12 1 Jean-Baptiste Barth
13 1 Jean-Baptiste Barth
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 1 Jean-Baptiste Barth
15 1 Jean-Baptiste Barth
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 2 Derric Atzrott
h2. Changing the layout of a page
18 2 Derric Atzrott
19 2 Derric Atzrott
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 2 Derric Atzrott
21 2 Derric Atzrott
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 3 Mischa The Evil
h2. Retrieve Redmine application configuration values
24 3 Mischa The Evil
25 3 Mischa The Evil
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 3 Mischa The Evil
27 3 Mischa The Evil
Example[1]:
28 3 Mischa The Evil
29 3 Mischa The Evil
Consider the following example configuration:
30 3 Mischa The Evil
<pre><code class="yaml">
31 3 Mischa The Evil
email_delivery:
32 3 Mischa The Evil
    delivery_method: :smtp
33 3 Mischa The Evil
    smtp_settings:
34 3 Mischa The Evil
      address: "myaddress.com" 
35 3 Mischa The Evil
      port: 25
36 3 Mischa The Evil
      domain: "mydomain.com"
37 3 Mischa The Evil
</code></pre>
38 3 Mischa The Evil
39 3 Mischa The Evil
Then the value of the @address@ configuration key can be retrieved by calling:
40 3 Mischa The Evil
<pre><code class="ruby">Redmine::Configuration['email_delivery']['smtp_settings'][:address]</code></pre>
41 3 Mischa The Evil
42 3 Mischa The Evil
fn1. source: message#59809
43 4 Mischa The Evil
44 4 Mischa The Evil
h2. Retrieve Redmine settings values
45 4 Mischa The Evil
46 4 Mischa The Evil
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 4 Mischa The Evil
48 4 Mischa The Evil
Examples:
49 4 Mischa The Evil
50 4 Mischa The Evil
* retrieve the value of the internal (Redmine core) 'welcome text' setting by calling:
51 4 Mischa The Evil
<pre><code class="ruby">
52 4 Mischa The Evil
Setting.welcome_text
53 4 Mischa The Evil
</code></pre>
54 4 Mischa The Evil
* retrieve the value of the 'notification_default' setting, as "provided" by the Polls plugin as documented in the [[Plugin Tutorial]], by calling:
55 4 Mischa The Evil
<pre><code class="ruby">
56 4 Mischa The Evil
Setting.plugin_polls['notification_default']
57 4 Mischa The Evil
</code></pre>
58 4 Mischa The Evil
59 4 Mischa The Evil
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 5 Mischa The Evil
h2. Require a certain Redmine version
62 5 Mischa The Evil
63 5 Mischa The Evil
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 5 Mischa The Evil
65 5 Mischa The Evil
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 5 Mischa The Evil
67 5 Mischa The Evil
{{collapse(View usage examples for requires_redmine method...)
68 5 Mischa The Evil
<pre><code class="ruby">
69 5 Mischa The Evil
# Requires Redmine 0.7.3 or higher
70 5 Mischa The Evil
requires_redmine :version_or_higher => '0.7.3'
71 5 Mischa The Evil
requires_redmine '0.7.3'
72 5 Mischa The Evil
73 5 Mischa The Evil
# Requires Redmine 0.7.x or higher
74 5 Mischa The Evil
requires_redmine '0.7'
75 5 Mischa The Evil
76 5 Mischa The Evil
# Requires a specific Redmine version
77 5 Mischa The Evil
requires_redmine :version => '0.7.3'              # 0.7.3 only
78 5 Mischa The Evil
requires_redmine :version => '0.7'                # 0.7.x
79 5 Mischa The Evil
requires_redmine :version => ['0.7.3', '0.8.0']   # 0.7.3 or 0.8.0
80 5 Mischa The Evil
81 5 Mischa The Evil
# Requires a Redmine version within a range
82 5 Mischa The Evil
requires_redmine :version => '0.7.3'..'0.9.1'     # >= 0.7.3 and <= 0.9.1
83 5 Mischa The Evil
requires_redmine :version => '0.7'..'0.9'         # >= 0.7.x and <= 0.9.x
84 5 Mischa The Evil
</code></pre>
85 5 Mischa The Evil
}}
86 6 Mischa The Evil
87 6 Mischa The Evil
h2. Require a certain Redmine plugin version
88 6 Mischa The Evil
89 6 Mischa The Evil
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 6 Mischa The Evil
91 7 Mischa The Evil
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 a) Redmine plugin and which are setup to stop Redmine with a message about a non-supported version if the version-requirement is not met.
92 6 Mischa The Evil
93 6 Mischa The Evil
{{collapse(View usage examples for requires_redmine_plugin method...)
94 6 Mischa The Evil
<pre><code class="ruby">
95 6 Mischa The Evil
# Requires a plugin named :foo version 0.7.3 or higher
96 6 Mischa The Evil
requires_redmine_plugin :foo, :version_or_higher => '0.7.3'
97 6 Mischa The Evil
requires_redmine_plugin :foo, '0.7.3'
98 6 Mischa The Evil
99 6 Mischa The Evil
# Requires a specific version of a Redmine plugin
100 6 Mischa The Evil
requires_redmine_plugin :foo, :version => '0.7.3'              # 0.7.3 only
101 6 Mischa The Evil
requires_redmine_plugin :foo, :version => ['0.7.3', '0.8.0']   # 0.7.3 or 0.8.0
102 6 Mischa The Evil
</code></pre>
103 6 Mischa The Evil
}}