Plugin settings

Add a configurable settings page to your Redmine plugin using the settings directive and access values with Setting.plugin_<name>.

Redmine allows plugins to expose a settings page in Administration > Plugins so administrators can configure plugin behavior without touching code. Settings are stored in the settings database table alongside Redmine’s own settings.

Declaring settings in init.rb

Call the settings method inside your Redmine::Plugin.register block. It accepts two keys:

• :default — a hash of default values applied when no setting has been saved yet.
• :partial — path to the settings form partial, relative to your plugin’s app/views/ directory.

# plugins/my_plugin/init.rb
Redmine::Plugin.register :my_plugin do
  name    'My Plugin'
  author  'Jane Smith'
  version '1.0.0'

  settings default: { 'notify' => true, 'max_items' => '10', 'api_key' => '' },
           partial: 'settings/my_plugin_settings'
end

Default values are used only when the setting has not yet been saved by an administrator. The :partial path is relative to plugins/my_plugin/app/views/ — the example above maps to plugins/my_plugin/app/views/settings/_my_plugin_settings.html.erb.

Creating the settings partial

Create the partial at the path declared in :partial. The plugin settings hash is available as the local variable settings.

<%# plugins/my_plugin/app/views/settings/_my_plugin_settings.html.erb %>

<p>
  <label>API key</label>
  <%= text_field_tag 'settings[api_key]',
                     settings['api_key'],
                     size: 60 %>
</p>

<p>
  <label>Max items per page</label>
  <%= text_field_tag 'settings[max_items]',
                     settings['max_items'],
                     size: 6 %>
</p>

<p>
  <label>
    <%= check_box_tag 'settings[notify]',
                      '1',
                      settings['notify'].to_s == 'true' %>
    Enable notifications
  </label>
</p>

All form fields must use text_field_tag, check_box_tag, select_tag, and similar _tag helpers with the name pattern settings[key_name]. Do not use form_for or model-backed helpers — Redmine’s settings controller handles the save automatically.

Reading settings in your plugin

Access saved settings anywhere in your plugin (models, controllers, views, jobs) using:

Setting.plugin_my_plugin
# => { 'notify' => true, 'max_items' => '10', 'api_key' => 'abc123' }

The method name is derived from the plugin id: Setting.plugin_<plugin_id>. To read a single value:

api_key  = Setting.plugin_my_plugin['api_key']
max_items = Setting.plugin_my_plugin['max_items'].to_i
notify   = Setting.plugin_my_plugin['notify'].to_s == 'true'

Wrap setting access in a helper method on your plugin’s module so the rest of your code is not scattered with string-key lookups:

module MyPlugin
  def self.settings
    Setting.plugin_my_plugin
  end

  def self.api_key
    settings['api_key'].presence
  end

  def self.max_items
    settings['max_items'].to_i
  end

  def self.notify?
    settings['notify'].to_s == 'true'
  end
end

Using settings in a controller

class MyPluginController < ApplicationController
  def index
    @max_items = Setting.plugin_my_plugin['max_items'].to_i
    @items     = MyItem.order(:created_at).limit(@max_items)
  end
end

Using settings in a view

<%# plugins/my_plugin/app/views/my_plugin/index.html.erb %>
<% settings = Setting.plugin_my_plugin %>

<% if settings['notify'].to_s == 'true' %>
  <p class="flash notice">Notifications are enabled.</p>
<% end %>

Where settings are stored

Redmine stores all plugin settings in the settings table as a single serialized value per plugin. The row has:

• name = plugin_<plugin_id> (e.g., plugin_my_plugin)
• value = YAML-serialized hash of all setting key-value pairs

Because the whole hash is serialized together, avoid storing large binary values in plugin settings.

Settings page in the UI

Once you add the settings declaration and create the partial, a Configure link appears next to your plugin on Administration > Plugins. Clicking it renders your partial inside Redmine’s standard settings form. Redmine handles saving and displaying flash messages.

The configurable? method on Redmine::Plugin returns true only when both :default and :partial are present. If :partial is missing, no Configure link appears.