##// END OF EJS Templates
jro_apps » redmine
RSS
remove trailing white-spaces from lib/redmine/plugin.rb...
Toshi MARUYAMA -
r11703:442532e31633
parent child
Show More
Side by Side Unified
Context file:
r11703:442532e31633 Loading diff...:
Show file before | Show file after | Hide comments
@@ -1,475 +1,475
1 1 # Redmine - project management software
2 2 # Copyright (C) 2006-2013 Jean-Philippe Lang
3 3 #
4 4 # This program is free software; you can redistribute it and/or
5 5 # modify it under the terms of the GNU General Public License
6 6 # as published by the Free Software Foundation; either version 2
7 7 # of the License, or (at your option) any later version.
8 8 #
9 9 # This program is distributed in the hope that it will be useful,
10 10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 12 # GNU General Public License for more details.
13 13 #
14 14 # You should have received a copy of the GNU General Public License
15 15 # along with this program; if not, write to the Free Software
16 16 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17 17
18 18 module Redmine #:nodoc:
19 19
20 20 class PluginNotFound < StandardError; end
21 21 class PluginRequirementError < StandardError; end
22 22
23 23 # Base class for Redmine plugins.
24 24 # Plugins are registered using the <tt>register</tt> class method that acts as the public constructor.
25 25 #
26 26 # Redmine::Plugin.register :example do
27 27 # name 'Example plugin'
28 28 # author 'John Smith'
29 29 # description 'This is an example plugin for Redmine'
30 30 # version '0.0.1'
31 31 # settings :default => {'foo'=>'bar'}, :partial => 'settings/settings'
32 32 # end
33 33 #
34 34 # === Plugin attributes
35 35 #
36 36 # +settings+ is an optional attribute that let the plugin be configurable.
37 37 # It must be a hash with the following keys:
38 38 # * <tt>:default</tt>: default value for the plugin settings
39 39 # * <tt>:partial</tt>: path of the configuration partial view, relative to the plugin <tt>app/views</tt> directory
40 40 # Example:
41 41 # settings :default => {'foo'=>'bar'}, :partial => 'settings/settings'
42 42 # In this example, the settings partial will be found here in the plugin directory: <tt>app/views/settings/_settings.rhtml</tt>.
43 43 #
44 44 # When rendered, the plugin settings value is available as the local variable +settings+
45 45 class Plugin
46 46 cattr_accessor :directory
47 47 self.directory = File.join(Rails.root, 'plugins')
48 48
49 49 cattr_accessor :public_directory
50 50 self.public_directory = File.join(Rails.root, 'public', 'plugin_assets')
51 51
52 52 @registered_plugins = {}
53 53 class << self
54 54 attr_reader :registered_plugins
55 55 private :new
56 56
57 57 def def_field(*names)
58 58 class_eval do
59 59 names.each do |name|
60 60 define_method(name) do |*args|
61 61 args.empty? ? instance_variable_get("@#{name}") : instance_variable_set("@#{name}", *args)
62 62 end
63 63 end
64 64 end
65 65 end
66 66 end
67 67 def_field :name, :description, :url, :author, :author_url, :version, :settings, :directory
68 68 attr_reader :id
69 69
70 70 # Plugin constructor
71 71 def self.register(id, &block)
72 72 p = new(id)
73 73 p.instance_eval(&block)
74 74
75 75 # Set a default name if it was not provided during registration
76 76 p.name(id.to_s.humanize) if p.name.nil?
77 77 # Set a default directory if it was not provided during registration
78 78 p.directory(File.join(self.directory, id.to_s)) if p.directory.nil?
79 79
80 80 # Adds plugin locales if any
81 81 # YAML translation files should be found under <plugin>/config/locales/
82 82 ::I18n.load_path += Dir.glob(File.join(p.directory, 'config', 'locales', '*.yml'))
83 83
84 84 # Prepends the app/views directory of the plugin to the view path
85 85 view_path = File.join(p.directory, 'app', 'views')
86 86 if File.directory?(view_path)
87 87 ActionController::Base.prepend_view_path(view_path)
88 88 ActionMailer::Base.prepend_view_path(view_path)
89 89 end
90 90
91 91 # Adds the app/{controllers,helpers,models} directories of the plugin to the autoload path
92 92 Dir.glob File.expand_path(File.join(p.directory, 'app', '{controllers,helpers,models}')) do |dir|
93 93 ActiveSupport::Dependencies.autoload_paths += [dir]
94 94 end
95 95
96 96 registered_plugins[id] = p
97 97 end
98 98
99 99 # Returns an array of all registered plugins
100 100 def self.all
101 101 registered_plugins.values.sort
102 102 end
103 103
104 104 # Finds a plugin by its id
105 105 # Returns a PluginNotFound exception if the plugin doesn't exist
106 106 def self.find(id)
107 107 registered_plugins[id.to_sym] || raise(PluginNotFound)
108 108 end
109 109
110 110 # Clears the registered plugins hash
111 111 # It doesn't unload installed plugins
112 112 def self.clear
113 113 @registered_plugins = {}
114 114 end
115 115
116 116 # Checks if a plugin is installed
117 117 #
118 118 # @param [String] id name of the plugin
119 119 def self.installed?(id)
120 120 registered_plugins[id.to_sym].present?
121 121 end
122 122
123 123 def self.load
124 124 Dir.glob(File.join(self.directory, '*')).sort.each do |directory|
125 125 if File.directory?(directory)
126 126 lib = File.join(directory, "lib")
127 127 if File.directory?(lib)
128 128 $:.unshift lib
129 129 ActiveSupport::Dependencies.autoload_paths += [lib]
130 130 end
131 131 initializer = File.join(directory, "init.rb")
132 132 if File.file?(initializer)
133 133 require initializer
134 134 end
135 135 end
136 136 end
137 137 end
138 138
139 139 def initialize(id)
140 140 @id = id.to_sym
141 141 end
142 142
143 143 def public_directory
144 144 File.join(self.class.public_directory, id.to_s)
145 145 end
146 146
147 147 def to_param
148 148 id
149 149 end
150 150
151 151 def assets_directory
152 152 File.join(directory, 'assets')
153 153 end
154 154
155 155 def <=>(plugin)
156 156 self.id.to_s <=> plugin.id.to_s
157 157 end
158 158
159 159 # Sets a requirement on Redmine version
160 160 # Raises a PluginRequirementError exception if the requirement is not met
161 161 #
162 162 # Examples
163 163 # # Requires Redmine 0.7.3 or higher
164 164 # requires_redmine :version_or_higher => '0.7.3'
165 165 # requires_redmine '0.7.3'
166 166 #
167 167 # # Requires Redmine 0.7.x or higher
168 168 # requires_redmine '0.7'
169 169 #
170 170 # # Requires a specific Redmine version
171 171 # requires_redmine :version => '0.7.3' # 0.7.3 only
172 172 # requires_redmine :version => '0.7' # 0.7.x
173 173 # requires_redmine :version => ['0.7.3', '0.8.0'] # 0.7.3 or 0.8.0
174 174 #
175 175 # # Requires a Redmine version within a range
176 176 # requires_redmine :version => '0.7.3'..'0.9.1' # >= 0.7.3 and <= 0.9.1
177 177 # requires_redmine :version => '0.7'..'0.9' # >= 0.7.x and <= 0.9.x
178 178 def requires_redmine(arg)
179 179 arg = { :version_or_higher => arg } unless arg.is_a?(Hash)
180 180 arg.assert_valid_keys(:version, :version_or_higher)
181 181
182 182 current = Redmine::VERSION.to_a
183 183 arg.each do |k, req|
184 184 case k
185 185 when :version_or_higher
186 186 raise ArgumentError.new(":version_or_higher accepts a version string only") unless req.is_a?(String)
187 187 unless compare_versions(req, current) <= 0
188 188 raise PluginRequirementError.new("#{id} plugin requires Redmine #{req} or higher but current is #{current.join('.')}")
189 189 end
190 190 when :version
191 191 req = [req] if req.is_a?(String)
192 192 if req.is_a?(Array)
193 193 unless req.detect {|ver| compare_versions(ver, current) == 0}
194 194 raise PluginRequirementError.new("#{id} plugin requires one the following Redmine versions: #{req.join(', ')} but current is #{current.join('.')}")
195 195 end
196 196 elsif req.is_a?(Range)
197 197 unless compare_versions(req.first, current) <= 0 && compare_versions(req.last, current) >= 0
198 198 raise PluginRequirementError.new("#{id} plugin requires a Redmine version between #{req.first} and #{req.last} but current is #{current.join('.')}")
199 199 end
200 200 else
201 201 raise ArgumentError.new(":version option accepts a version string, an array or a range of versions")
202 202 end
203 203 end
204 204 end
205 205 true
206 206 end
207 207
208 208 def compare_versions(requirement, current)
209 209 requirement = requirement.split('.').collect(&:to_i)
210 210 requirement <=> current.slice(0, requirement.size)
211 211 end
212 212 private :compare_versions
213 213
214 214 # Sets a requirement on a Redmine plugin version
215 215 # Raises a PluginRequirementError exception if the requirement is not met
216 216 #
217 217 # Examples
218 218 # # Requires a plugin named :foo version 0.7.3 or higher
219 219 # requires_redmine_plugin :foo, :version_or_higher => '0.7.3'
220 220 # requires_redmine_plugin :foo, '0.7.3'
221 221 #
222 222 # # Requires a specific version of a Redmine plugin
223 223 # requires_redmine_plugin :foo, :version => '0.7.3' # 0.7.3 only
224 224 # requires_redmine_plugin :foo, :version => ['0.7.3', '0.8.0'] # 0.7.3 or 0.8.0
225 225 def requires_redmine_plugin(plugin_name, arg)
226 226 arg = { :version_or_higher => arg } unless arg.is_a?(Hash)
227 227 arg.assert_valid_keys(:version, :version_or_higher)
228 228
229 229 plugin = Plugin.find(plugin_name)
230 230 current = plugin.version.split('.').collect(&:to_i)
231 231
232 232 arg.each do |k, v|
233 233 v = [] << v unless v.is_a?(Array)
234 234 versions = v.collect {|s| s.split('.').collect(&:to_i)}
235 235 case k
236 236 when :version_or_higher
237 237 raise ArgumentError.new("wrong number of versions (#{versions.size} for 1)") unless versions.size == 1
238 238 unless (current <=> versions.first) >= 0
239 239 raise PluginRequirementError.new("#{id} plugin requires the #{plugin_name} plugin #{v} or higher but current is #{current.join('.')}")
240 240 end
241 241 when :version
242 242 unless versions.include?(current.slice(0,3))
243 243 raise PluginRequirementError.new("#{id} plugin requires one the following versions of #{plugin_name}: #{v.join(', ')} but current is #{current.join('.')}")
244 244 end
245 245 end
246 246 end
247 247 true
248 248 end
249 249
250 250 # Adds an item to the given +menu+.
251 251 # The +id+ parameter (equals to the project id) is automatically added to the url.
252 252 # menu :project_menu, :plugin_example, { :controller => 'example', :action => 'say_hello' }, :caption => 'Sample'
253 253 #
254 254 # +name+ parameter can be: :top_menu, :account_menu, :application_menu or :project_menu
255 255 #
256 256 def menu(menu, item, url, options={})
257 257 Redmine::MenuManager.map(menu).push(item, url, options)
258 258 end
259 259 alias :add_menu_item :menu
260 260
261 261 # Removes +item+ from the given +menu+.
262 262 def delete_menu_item(menu, item)
263 263 Redmine::MenuManager.map(menu).delete(item)
264 264 end
265 265
266 266 # Defines a permission called +name+ for the given +actions+.
267 267 #
268 268 # The +actions+ argument is a hash with controllers as keys and actions as values (a single value or an array):
269 269 # permission :destroy_contacts, { :contacts => :destroy }
270 270 # permission :view_contacts, { :contacts => [:index, :show] }
271 271 #
272 272 # The +options+ argument is a hash that accept the following keys:
273 273 # * :public => the permission is public if set to true (implicitly given to any user)
274 274 # * :require => can be set to one of the following values to restrict users the permission can be given to: :loggedin, :member
275 275 # * :read => set it to true so that the permission is still granted on closed projects
276 276 #
277 277 # Examples
278 278 # # A permission that is implicitly given to any user
279 279 # # This permission won't appear on the Roles & Permissions setup screen
280 280 # permission :say_hello, { :example => :say_hello }, :public => true, :read => true
281 281 #
282 282 # # A permission that can be given to any user
283 283 # permission :say_hello, { :example => :say_hello }
284 284 #
285 285 # # A permission that can be given to registered users only
286 286 # permission :say_hello, { :example => :say_hello }, :require => :loggedin
287 287 #
288 288 # # A permission that can be given to project members only
289 289 # permission :say_hello, { :example => :say_hello }, :require => :member
290 290 def permission(name, actions, options = {})
291 291 if @project_module
292 292 Redmine::AccessControl.map {|map| map.project_module(@project_module) {|map|map.permission(name, actions, options)}}
293 293 else
294 294 Redmine::AccessControl.map {|map| map.permission(name, actions, options)}
295 295 end
296 296 end
297 297
298 298 # Defines a project module, that can be enabled/disabled for each project.
299 299 # Permissions defined inside +block+ will be bind to the module.
300 300 #
301 301 # project_module :things do
302 302 # permission :view_contacts, { :contacts => [:list, :show] }, :public => true
303 303 # permission :destroy_contacts, { :contacts => :destroy }
304 304 # end
305 305 def project_module(name, &block)
306 306 @project_module = name
307 307 self.instance_eval(&block)
308 308 @project_module = nil
309 309 end
310 310
311 311 # Registers an activity provider.
312 312 #
313 313 # Options:
314 314 # * <tt>:class_name</tt> - one or more model(s) that provide these events (inferred from event_type by default)
315 315 # * <tt>:default</tt> - setting this option to false will make the events not displayed by default
316 316 #
317 317 # A model can provide several activity event types.
318 318 #
319 319 # Examples:
320 320 # register :news
321 321 # register :scrums, :class_name => 'Meeting'
322 322 # register :issues, :class_name => ['Issue', 'Journal']
323 323 #
324 324 # Retrieving events:
325 325 # Associated model(s) must implement the find_events class method.
326 326 # ActiveRecord models can use acts_as_activity_provider as a way to implement this class method.
327 327 #
328 328 # The following call should return all the scrum events visible by current user that occured in the 5 last days:
329 329 # Meeting.find_events('scrums', User.current, 5.days.ago, Date.today)
330 330 # Meeting.find_events('scrums', User.current, 5.days.ago, Date.today, :project => foo) # events for project foo only
331 331 #
332 332 # Note that :view_scrums permission is required to view these events in the activity view.
333 333 def activity_provider(*args)
334 334 Redmine::Activity.register(*args)
335 335 end
336 336
337 337 # Registers a wiki formatter.
338 338 #
339 339 # Parameters:
340 340 # * +name+ - human-readable name
341 341 # * +formatter+ - formatter class, which should have an instance method +to_html+
342 342 # * +helper+ - helper module, which will be included by wiki pages
343 343 def wiki_format_provider(name, formatter, helper)
344 344 Redmine::WikiFormatting.register(name, formatter, helper)
345 345 end
346 346
347 347 # Returns +true+ if the plugin can be configured.
348 348 def configurable?
349 349 settings && settings.is_a?(Hash) && !settings[:partial].blank?
350 350 end
351 351
352 352 def mirror_assets
353 353 source = assets_directory
354 354 destination = public_directory
355 355 return unless File.directory?(source)
356 356
357 357 source_files = Dir[source + "/**/*"]
358 358 source_dirs = source_files.select { |d| File.directory?(d) }
359 359 source_files -= source_dirs
360 360
361 361 unless source_files.empty?
362 362 base_target_dir = File.join(destination, File.dirname(source_files.first).gsub(source, ''))
363 363 begin
364 364 FileUtils.mkdir_p(base_target_dir)
365 365 rescue Exception => e
366 366 raise "Could not create directory #{base_target_dir}: " + e.message
367 367 end
368 368 end
369 369
370 370 source_dirs.each do |dir|
371 371 # strip down these paths so we have simple, relative paths we can
372 372 # add to the destination
373 373 target_dir = File.join(destination, dir.gsub(source, ''))
374 374 begin
375 375 FileUtils.mkdir_p(target_dir)
376 376 rescue Exception => e
377 377 raise "Could not create directory #{target_dir}: " + e.message
378 378 end
379 379 end
380 380
381 381 source_files.each do |file|
382 382 begin
383 383 target = File.join(destination, file.gsub(source, ''))
384 384 unless File.exist?(target) && FileUtils.identical?(file, target)
385 385 FileUtils.cp(file, target)
386 386 end
387 387 rescue Exception => e
388 388 raise "Could not copy #{file} to #{target}: " + e.message
389 389 end
390 390 end
391 391 end
392 392
393 393 # Mirrors assets from one or all plugins to public/plugin_assets
394 394 def self.mirror_assets(name=nil)
395 395 if name.present?
396 396 find(name).mirror_assets
397 397 else
398 398 all.each do |plugin|
399 399 plugin.mirror_assets
400 400 end
401 401 end
402 402 end
403 403
404 404 # The directory containing this plugin's migrations (<tt>plugin/db/migrate</tt>)
405 405 def migration_directory
406 406 File.join(Rails.root, 'plugins', id.to_s, 'db', 'migrate')
407 407 end
408 408
409 409 # Returns the version number of the latest migration for this plugin. Returns
410 410 # nil if this plugin has no migrations.
411 411 def latest_migration
412 412 migrations.last
413 413 end
414 414
415 415 # Returns the version numbers of all migrations for this plugin.
416 416 def migrations
417 417 migrations = Dir[migration_directory+"/*.rb"]
418 418 migrations.map { |p| File.basename(p).match(/0*(\d+)\_/)[1].to_i }.sort
419 419 end
420 420
421 421 # Migrate this plugin to the given version
422 422 def migrate(version = nil)
423 423 puts "Migrating #{id} (#{name})..."
424 424 Redmine::Plugin::Migrator.migrate_plugin(self, version)
425 425 end
426 426
427 427 # Migrates all plugins or a single plugin to a given version
428 428 # Exemples:
429 429 # Plugin.migrate
430 430 # Plugin.migrate('sample_plugin')
431 431 # Plugin.migrate('sample_plugin', 1)
432 432 #
433 433 def self.migrate(name=nil, version=nil)
434 434 if name.present?
435 435 find(name).migrate(version)
436 436 else
437 437 all.each do |plugin|
438 438 plugin.migrate
439 439 end
440 440 end
441 441 end
442 442
443 443 class Migrator < ActiveRecord::Migrator
444 444 # We need to be able to set the 'current' plugin being migrated.
445 445 cattr_accessor :current_plugin
446
446
447 447 class << self
448 448 # Runs the migrations from a plugin, up (or down) to the version given
449 449 def migrate_plugin(plugin, version)
450 450 self.current_plugin = plugin
451 451 return if current_version(plugin) == version
452 452 migrate(plugin.migration_directory, version)
453 453 end
454
454
455 455 def current_version(plugin=current_plugin)
456 456 # Delete migrations that don't match .. to_i will work because the number comes first
457 457 ::ActiveRecord::Base.connection.select_values(
458 458 "SELECT version FROM #{schema_migrations_table_name}"
459 459 ).delete_if{ |v| v.match(/-#{plugin.id}/) == nil }.map(&:to_i).max || 0
460 460 end
461 461 end
462
462
463 463 def migrated
464 464 sm_table = self.class.schema_migrations_table_name
465 465 ::ActiveRecord::Base.connection.select_values(
466 466 "SELECT version FROM #{sm_table}"
467 467 ).delete_if{ |v| v.match(/-#{current_plugin.id}/) == nil }.map(&:to_i).sort
468 468 end
469
469
470 470 def record_version_state_after_migrating(version)
471 471 super(version.to_s + "-" + current_plugin.id.to_s)
472 472 end
473 473 end
474 474 end
475 475 end
General Comments 0
You need to be logged in to leave comments. Login now