Class: Redmine::Plugin
- Inherits:
-
Object
- Object
- Redmine::Plugin
- Defined in:
- lib/redmine/plugin.rb
Overview
Base class for Redmine plugins. Plugins are registered using the register
class method that acts as the public constructor.
Redmine::Plugin.register :example do
name 'Example plugin'
'John Smith'
description 'This is an example plugin for Redmine'
version '0.0.1'
settings :default => {'foo'=>'bar'}, :partial => 'settings/settings'
end
Plugin attributes
settings
is an optional attribute that let the plugin be configurable. It must be a hash with the following keys:
-
:default
: default value for the plugin settings -
:partial
: path of the configuration partial view, relative to the pluginapp/views
directory
Example:
settings :default => {'foo'=>'bar'}, :partial => 'settings/settings'
In this example, the settings partial will be found here in the plugin directory: app/views/settings/_settings.rhtml
.
When rendered, the plugin settings value is available as the local variable settings
Defined Under Namespace
Classes: MigrationContext, Migrator
Class Attribute Summary collapse
-
.registered_plugins ⇒ Object
readonly
Returns the value of attribute registered_plugins.
Instance Attribute Summary collapse
-
#id ⇒ Object
readonly
Returns the value of attribute id.
Class Method Summary collapse
-
.all ⇒ Object
Returns an array of all registered plugins.
-
.clear ⇒ Object
Clears the registered plugins hash It doesn't unload installed plugins.
- .def_field(*names) ⇒ Object
-
.find(id) ⇒ Object
Finds a plugin by its id Returns a PluginNotFound exception if the plugin doesn't exist.
-
.installed?(id) ⇒ Boolean
Checks if a plugin is installed.
- .load ⇒ Object
-
.migrate(name = nil, version = nil) ⇒ Object
Migrates all plugins or a single plugin to a given version Exemples: Plugin.migrate Plugin.migrate('sample_plugin') Plugin.migrate('sample_plugin', 1).
-
.mirror_assets(name = nil) ⇒ Object
Mirrors assets from one or all plugins to public/plugin_assets.
-
.register(id, &block) ⇒ Object
Plugin constructor: instanciates a new Redmine::Plugin with given
id
and make it evaluate the givenblock
. -
.unregister(id) ⇒ Object
Removes a plugin from the registered plugins It doesn't unload the plugin.
Instance Method Summary collapse
- #<=>(plugin) ⇒ Object
-
#activity_provider(*args) ⇒ Object
Registers an activity provider.
-
#assets_directory ⇒ Object
Returns the absolute path to the plugin assets directory.
-
#configurable? ⇒ Boolean
Returns
true
if the plugin can be configured. -
#delete_menu_item(menu, item) ⇒ Object
Removes
item
from the givenmenu
. -
#initialize(id) ⇒ Plugin
constructor
A new instance of Plugin.
-
#latest_migration ⇒ Object
Returns the version number of the latest migration for this plugin.
-
#menu(menu, item, url, options = {}) ⇒ Object
(also: #add_menu_item)
Adds an item to the given
menu
. -
#migrate(version = nil) ⇒ Object
Migrate this plugin to the given version.
-
#migration_directory ⇒ Object
The directory containing this plugin's migrations (
plugin/db/migrate
). -
#migrations ⇒ Object
Returns the version numbers of all migrations for this plugin.
- #mirror_assets ⇒ Object
-
#permission(name, actions, options = {}) ⇒ Object
Defines a permission called
name
for the givenactions
. -
#project_module(name, &block) ⇒ Object
Defines a project module, that can be enabled/disabled for each project.
- #public_directory ⇒ Object
-
#requires_redmine(arg) ⇒ Object
Sets a requirement on Redmine version Raises a PluginRequirementError exception if the requirement is not met.
-
#requires_redmine_plugin(plugin_name, arg) ⇒ Object
Sets a requirement on a Redmine plugin version Raises a PluginRequirementError exception if the requirement is not met.
- #to_param ⇒ Object
-
#wiki_format_provider(name, *args) ⇒ Object
Registers a wiki formatter.
Constructor Details
#initialize(id) ⇒ Plugin
Returns a new instance of Plugin.
187 188 189 |
# File 'lib/redmine/plugin.rb', line 187 def initialize(id) @id = id.to_sym end |
Class Attribute Details
.registered_plugins ⇒ Object (readonly)
Returns the value of attribute registered_plugins
65 66 67 |
# File 'lib/redmine/plugin.rb', line 65 def registered_plugins @registered_plugins end |
Instance Attribute Details
#id ⇒ Object (readonly)
Returns the value of attribute id
79 80 81 |
# File 'lib/redmine/plugin.rb', line 79 def id @id end |
Class Method Details
.all ⇒ Object
Returns an array of all registered plugins
142 143 144 |
# File 'lib/redmine/plugin.rb', line 142 def self.all registered_plugins.values.sort end |
.clear ⇒ Object
Clears the registered plugins hash It doesn't unload installed plugins
154 155 156 |
# File 'lib/redmine/plugin.rb', line 154 def self.clear @registered_plugins = {} end |
.def_field(*names) ⇒ Object
68 69 70 71 72 73 74 75 76 |
# File 'lib/redmine/plugin.rb', line 68 def def_field(*names) class_eval do names.each do |name| define_method(name) do |*args| args.empty? ? instance_variable_get("@#{name}") : instance_variable_set("@#{name}", *args) end end end end |
.find(id) ⇒ Object
Finds a plugin by its id Returns a PluginNotFound exception if the plugin doesn't exist
148 149 150 |
# File 'lib/redmine/plugin.rb', line 148 def self.find(id) registered_plugins[id.to_sym] || raise(PluginNotFound) end |
.installed?(id) ⇒ Boolean
Checks if a plugin is installed
167 168 169 |
# File 'lib/redmine/plugin.rb', line 167 def self.installed?(id) registered_plugins[id.to_sym].present? end |
.load ⇒ Object
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 |
# File 'lib/redmine/plugin.rb', line 171 def self.load Dir.glob(File.join(self.directory, '*')).sort.each do |directory| if File.directory?(directory) lib = File.join(directory, "lib") if File.directory?(lib) $:.unshift lib ActiveSupport::Dependencies.autoload_paths += [lib] end initializer = File.join(directory, "init.rb") if File.file?(initializer) require initializer end end end end |
.migrate(name = nil, version = nil) ⇒ Object
492 493 494 495 496 497 498 499 500 |
# File 'lib/redmine/plugin.rb', line 492 def self.migrate(name=nil, version=nil) if name.present? find(name).migrate(version) else all.each do |plugin| plugin.migrate end end end |
.mirror_assets(name = nil) ⇒ Object
Mirrors assets from one or all plugins to public/plugin_assets
454 455 456 457 458 459 460 461 462 |
# File 'lib/redmine/plugin.rb', line 454 def self.mirror_assets(name=nil) if name.present? find(name).mirror_assets else all.each do |plugin| plugin.mirror_assets end end end |
.register(id, &block) ⇒ Object
Plugin constructor: instanciates a new Redmine::Plugin with given id
and make it evaluate the given block
Example
Redmine::Plugin.register :example do
name 'Example plugin'
'John Smith'
description 'This is an example plugin for Redmine'
version '0.0.1'
requires_redmine version_or_higher: '3.0.0'
end
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 |
# File 'lib/redmine/plugin.rb', line 92 def self.register(id, &block) p = new(id) p.instance_eval(&block) # Set a default name if it was not provided during registration p.name(id.to_s.humanize) if p.name.nil? # Set a default directory if it was not provided during registration p.directory(File.join(self.directory, id.to_s)) if p.directory.nil? unless File.directory?(p.directory) raise PluginNotFound, "Plugin not found. The directory for plugin #{p.id} should be #{p.directory}." end # Adds plugin locales if any # YAML translation files should be found under <plugin>/config/locales/ Rails.application.config.i18n.load_path += Dir.glob(File.join(p.directory, 'config', 'locales', '*.yml')) # Prepends the app/views directory of the plugin to the view path view_path = File.join(p.directory, 'app', 'views') if File.directory?(view_path) ActionController::Base.prepend_view_path(view_path) ActionMailer::Base.prepend_view_path(view_path) end # Add the plugin directories to rails autoload paths engine_cfg = Rails::Engine::Configuration.new(p.directory) engine_cfg.paths.add 'lib', eager_load: true Rails.application.config.eager_load_paths += engine_cfg.eager_load_paths Rails.application.config.autoload_once_paths += engine_cfg.autoload_once_paths Rails.application.config.autoload_paths += engine_cfg.autoload_paths ActiveSupport::Dependencies.autoload_paths += engine_cfg.eager_load_paths + engine_cfg.autoload_once_paths + engine_cfg.autoload_paths # Defines plugin setting if present if p.settings Setting.define_plugin_setting p end # Warn for potential settings[:partial] collisions if p.configurable? partial = p.settings[:partial] if @used_partials[partial] Rails.logger.warn "WARNING: settings partial '#{partial}' is declared in '#{p.id}' plugin but it is already used by plugin '#{@used_partials[partial]}'. Only one settings view will be used. You may want to contact those plugins authors to fix this." end @used_partials[partial] = p.id end registered_plugins[id] = p end |
.unregister(id) ⇒ Object
Removes a plugin from the registered plugins It doesn't unload the plugin
160 161 162 |
# File 'lib/redmine/plugin.rb', line 160 def self.unregister(id) @registered_plugins.delete(id) end |
Instance Method Details
#<=>(plugin) ⇒ Object
204 205 206 |
# File 'lib/redmine/plugin.rb', line 204 def <=>(plugin) self.id.to_s <=> plugin.id.to_s end |
#activity_provider(*args) ⇒ Object
Registers an activity provider.
Options:
-
:class_name
- one or more model(s) that provide these events (inferred from event_type by default) -
:default
- setting this option to false will make the events not displayed by default
A model can provide several activity event types.
Examples:
register :news
register :scrums, :class_name => 'Meeting'
register :issues, :class_name => ['Issue', 'Journal']
Retrieving events: Associated model(s) must implement the find_events class method. ActiveRecord models can use acts_as_activity_provider as a way to implement this class method.
The following call should return all the scrum events visible by current user that occurred in the 5 last days:
Meeting.find_events('scrums', User.current, 5.days.ago, Date.today)
Meeting.find_events('scrums', User.current, 5.days.ago, Date.today, :project => foo) # events for project foo only
Note that :view_scrums permission is required to view these events in the activity view.
386 387 388 |
# File 'lib/redmine/plugin.rb', line 386 def activity_provider(*args) Redmine::Activity.register(*args) end |
#assets_directory ⇒ Object
Returns the absolute path to the plugin assets directory
200 201 202 |
# File 'lib/redmine/plugin.rb', line 200 def assets_directory File.join(directory, 'assets') end |
#configurable? ⇒ Boolean
Returns true
if the plugin can be configured.
408 409 410 |
# File 'lib/redmine/plugin.rb', line 408 def configurable? settings && settings.is_a?(Hash) && !settings[:partial].blank? end |
#delete_menu_item(menu, item) ⇒ Object
Removes item
from the given menu
.
315 316 317 |
# File 'lib/redmine/plugin.rb', line 315 def (, item) Redmine::MenuManager.map().delete(item) end |
#latest_migration ⇒ Object
Returns the version number of the latest migration for this plugin. Returns nil if this plugin has no migrations.
471 472 473 |
# File 'lib/redmine/plugin.rb', line 471 def latest_migration migrations.last end |
#menu(menu, item, url, options = {}) ⇒ Object Also known as:
Adds an item to the given menu
. The id
parameter (equals to the project id) is automatically added to the url.
:project_menu, :plugin_example, { :controller => 'example', :action => 'say_hello' }, :caption => 'Sample'
name
parameter can be: :top_menu, :account_menu, :application_menu or :project_menu
309 310 311 |
# File 'lib/redmine/plugin.rb', line 309 def (, item, url, ={}) Redmine::MenuManager.map().push(item, url, ) end |
#migrate(version = nil) ⇒ Object
Migrate this plugin to the given version
482 483 484 |
# File 'lib/redmine/plugin.rb', line 482 def migrate(version = nil) Redmine::Plugin::Migrator.migrate_plugin(self, version) end |
#migration_directory ⇒ Object
The directory containing this plugin's migrations (plugin/db/migrate
)
465 466 467 |
# File 'lib/redmine/plugin.rb', line 465 def migration_directory File.join(directory, 'db', 'migrate') end |
#migrations ⇒ Object
Returns the version numbers of all migrations for this plugin.
476 477 478 479 |
# File 'lib/redmine/plugin.rb', line 476 def migrations migrations = Dir[migration_directory+"/*.rb"] migrations.map { |p| File.basename(p).match(/0*(\d+)\_/)[1].to_i }.sort end |
#mirror_assets ⇒ Object
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 |
# File 'lib/redmine/plugin.rb', line 412 def mirror_assets source = assets_directory destination = public_directory return unless File.directory?(source) source_files = Dir[source + "/**/*"] source_dirs = source_files.select { |d| File.directory?(d) } source_files -= source_dirs unless source_files.empty? base_target_dir = File.join(destination, File.dirname(source_files.first).gsub(source, '')) begin FileUtils.mkdir_p(base_target_dir) rescue => e raise "Could not create directory #{base_target_dir}: " + e. end end source_dirs.each do |dir| # strip down these paths so we have simple, relative paths we can # add to the destination target_dir = File.join(destination, dir.gsub(source, '')) begin FileUtils.mkdir_p(target_dir) rescue => e raise "Could not create directory #{target_dir}: " + e. end end source_files.each do |file| begin target = File.join(destination, file.gsub(source, '')) unless File.exist?(target) && FileUtils.identical?(file, target) FileUtils.cp(file, target) end rescue => e raise "Could not copy #{file} to #{target}: " + e. end end end |
#permission(name, actions, options = {}) ⇒ Object
Defines a permission called name
for the given actions
.
The actions
argument is a hash with controllers as keys and actions as values (a single value or an array):
:destroy_contacts, { :contacts => :destroy }
:view_contacts, { :contacts => [:index, :show] }
The options
argument is a hash that accept the following keys:
-
:public => the permission is public if set to true (implicitly given to any user)
-
:require => can be set to one of the following values to restrict users the permission can be given to: :loggedin, :member
-
:read => set it to true so that the permission is still granted on closed projects
Examples
# A permission that is implicitly given to any user
# This permission won't appear on the Roles & Permissions setup screen
:say_hello, { :example => :say_hello }, :public => true, :read => true
# A permission that can be given to any user
:say_hello, { :example => :say_hello }
# A permission that can be given to registered users only
:say_hello, { :example => :say_hello }, :require => :loggedin
# A permission that can be given to project members only
:say_hello, { :example => :say_hello }, :require => :member
343 344 345 346 347 348 349 |
# File 'lib/redmine/plugin.rb', line 343 def (name, actions, = {}) if @project_module Redmine::AccessControl.map {|map| map.project_module(@project_module) {|map| map.(name, actions, )}} else Redmine::AccessControl.map {|map| map.(name, actions, )} end end |
#project_module(name, &block) ⇒ Object
Defines a project module, that can be enabled/disabled for each project. Permissions defined inside block
will be bind to the module.
project_module :things do
:view_contacts, { :contacts => [:list, :show] }, :public => true
:destroy_contacts, { :contacts => :destroy }
end
358 359 360 361 362 |
# File 'lib/redmine/plugin.rb', line 358 def project_module(name, &block) @project_module = name self.instance_eval(&block) @project_module = nil end |
#public_directory ⇒ Object
191 192 193 |
# File 'lib/redmine/plugin.rb', line 191 def public_directory File.join(self.class.public_directory, id.to_s) end |
#requires_redmine(arg) ⇒ Object
Sets a requirement on Redmine version Raises a PluginRequirementError exception if the requirement is not met
Examples
# Requires Redmine 0.7.3 or higher
requires_redmine :version_or_higher => '0.7.3'
requires_redmine '0.7.3'
# Requires Redmine 0.7.x or higher
requires_redmine '0.7'
# Requires a specific Redmine version
requires_redmine :version => '0.7.3' # 0.7.3 only
requires_redmine :version => '0.7' # 0.7.x
requires_redmine :version => ['0.7.3', '0.8.0'] # 0.7.3 or 0.8.0
# Requires a Redmine version within a range
requires_redmine :version => '0.7.3'..'0.9.1' # >= 0.7.3 and <= 0.9.1
requires_redmine :version => '0.7'..'0.9' # >= 0.7.x and <= 0.9.x
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 |
# File 'lib/redmine/plugin.rb', line 227 def requires_redmine(arg) arg = { :version_or_higher => arg } unless arg.is_a?(Hash) arg.assert_valid_keys(:version, :version_or_higher) current = Redmine::VERSION.to_a arg.each do |k, req| case k when :version_or_higher raise ArgumentError.new(":version_or_higher accepts a version string only") unless req.is_a?(String) unless compare_versions(req, current) <= 0 raise PluginRequirementError.new("#{id} plugin requires Redmine #{req} or higher but current is #{current.join('.')}") end when :version req = [req] if req.is_a?(String) if req.is_a?(Array) unless req.detect {|ver| compare_versions(ver, current) == 0} raise PluginRequirementError.new("#{id} plugin requires one the following Redmine versions: #{req.join(', ')} but current is #{current.join('.')}") end elsif req.is_a?(Range) unless compare_versions(req.first, current) <= 0 && compare_versions(req.last, current) >= 0 raise PluginRequirementError.new("#{id} plugin requires a Redmine version between #{req.first} and #{req.last} but current is #{current.join('.')}") end else raise ArgumentError.new(":version option accepts a version string, an array or a range of versions") end end end true end |
#requires_redmine_plugin(plugin_name, arg) ⇒ Object
Sets a requirement on a Redmine plugin version Raises a PluginRequirementError exception if the requirement is not met
Examples
# Requires a plugin named :foo version 0.7.3 or higher
requires_redmine_plugin :foo, :version_or_higher => '0.7.3'
requires_redmine_plugin :foo, '0.7.3'
# Requires a specific version of a Redmine plugin
requires_redmine_plugin :foo, :version => '0.7.3' # 0.7.3 only
requires_redmine_plugin :foo, :version => ['0.7.3', '0.8.0'] # 0.7.3 or 0.8.0
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 |
# File 'lib/redmine/plugin.rb', line 274 def requires_redmine_plugin(plugin_name, arg) arg = { :version_or_higher => arg } unless arg.is_a?(Hash) arg.assert_valid_keys(:version, :version_or_higher) begin plugin = Plugin.find(plugin_name) rescue PluginNotFound raise PluginRequirementError.new("#{id} plugin requires the #{plugin_name} plugin") end current = plugin.version.split('.').collect(&:to_i) arg.each do |k, v| v = [] << v unless v.is_a?(Array) versions = v.collect {|s| s.split('.').collect(&:to_i)} case k when :version_or_higher raise ArgumentError.new("wrong number of versions (#{versions.size} for 1)") unless versions.size == 1 unless (current <=> versions.first) >= 0 raise PluginRequirementError.new("#{id} plugin requires the #{plugin_name} plugin #{v} or higher but current is #{current.join('.')}") end when :version unless versions.include?(current.slice(0,3)) raise PluginRequirementError.new("#{id} plugin requires one the following versions of #{plugin_name}: #{v.join(', ')} but current is #{current.join('.')}") end end end true end |
#to_param ⇒ Object
195 196 197 |
# File 'lib/redmine/plugin.rb', line 195 def to_param id end |
#wiki_format_provider(name, *args) ⇒ Object
Registers a wiki formatter.
Parameters:
-
name
- formatter name -
formatter
- formatter class, which should have an instance methodto_html
-
helper
- helper module, which will be included by wiki pages (optional) -
html_parser
class reponsible for converting HTML to wiki text (optional) -
options
- a Hash of options (optional)-
:label - label for the formatter displayed in application settings
-
Examples:
wiki_format_provider(:custom_formatter, CustomFormatter, :label => "My custom formatter")
403 404 405 |
# File 'lib/redmine/plugin.rb', line 403 def wiki_format_provider(name, *args) Redmine::WikiFormatting.register(name, *args) end |