module Middleman::Extensions
The Extensions
module is used to handle global registration and loading of Middleman
Extensions
.
The application-facing extension API ({Middleman::CoreExtensions::Extensions#activate activate}, etc) is in {Middleman::CoreExtensions::Extensions} in ‘middleman-core/core_extensions/extensions.rb`.
Constants
- AutoActivation
Attributes
@api private A hash of all registered extensions. Registered extensions are not necessarily active - this is the set of all extensions that are known to Middleman
. @return [Hash{Symbol => Class<Middleman::Extension>, Proc}] A directory of known extensions indexed by the name they were registered under. The value may be a Proc, which can be lazily called to return an extension class.
Public Class Methods
Source
# File lib/middleman-core/extensions.rb, line 116 def auto_activate(group, app) @auto_activate[group].each do |descriptor| next unless descriptor[:modes] == :all || descriptor[:modes].include?(app.config[:mode]) app.extensions.activate descriptor[:name] end end
@api private Load autoactivatable extensions for the given env. @param [Symbol] group The name of the auto_activation group. @param [Middleman::Application] app An instance of the app.
Source
# File lib/middleman-core/extensions.rb, line 108 def auto_activated @auto_activate.values.map(&:to_a).flatten.map(&:name) end
@api private A flattened list of all extensions which are automatically activated @return [Array<Symbol>] A list of extension names which are automatically activated.
Source
# File lib/middleman-core/extensions.rb, line 82 def load(name) raise 'Extension name must be a symbol' unless name.is_a?(Symbol) unless registered.key?(name) raise "Unknown Extension: #{name}. Check the name and make sure you have referenced the extension's gem in your Gemfile." end extension_class = registered[name] if extension_class.is_a?(Proc) extension_class = extension_class.call registered[name] = extension_class end unless extension_class.ancestors.include?(::Middleman::Extension) raise "Tried to activate old-style extension: #{name}. They are no longer supported." end # Set the extension's name to whatever it was registered as. extension_class.ext_name = name extension_class end
@api private Load an extension by name, lazily evaluating the block provided to {#register} if necessary. @param [Symbol] name The name of the extension @return [Class<Middleman::Extension>] A {Middleman::Extension} class implementing the extension
Source
# File lib/middleman-core/extensions.rb, line 124 def load_settings(app) registered.each do |name, _| begin ext = load(name) unless ext.global_config.all_settings.empty? app.config.load_settings(ext.global_config.all_settings) end rescue LoadError end end end
Source
# File lib/middleman-core/extensions.rb, line 52 def register(name, extension_class=nil, options={}, &block) raise 'Extension name must be a symbol' unless name.is_a?(Symbol) # If we've already got an extension registered under this name, bail out # raise "There is a already an extension registered with the name '#{name}'" if registered.key?(name) # If the extension is defined with a block, grab options out of the "extension_class" parameter. if extension_class && block_given? && options.empty? && extension_class.is_a?(Hash) options = extension_class extension_class = nil end registered[name] = if block_given? block elsif extension_class && extension_class.ancestors.include?(::Middleman::Extension) extension_class else raise 'You must provide a Middleman::Extension or a block that returns a Middleman::Extension' end return unless options[:auto_activate] descriptor = AutoActivation.new(name, options[:modes] || :all) @auto_activate[options[:auto_activate]] << descriptor end
Register a new extension. Choose a name which will be used to activate the extension in ‘config.rb`, like this:
activate :my_extension
Provide your extension class either as the second parameter:
Middleman::Extensions.register(:my_extension, MyExtension)
Or better, return it from a block, which allows you to lazily require the implementation:
Middleman::Extensions.register :my_extension do require 'my_extension' MyExtension end
@param [Symbol] name The name of the extension @param [Class<Middleman::Extension>] extension_class The extension class (Must inherit from {Middleman::Extension}) @option options [Boolean] :auto_activate If this is set to a lifecycle event (:before_configuration or :before_sitemap), this extension will be automatically activated at that point.
This is intended for use with built-in Middleman extensions and should not be used by third-party extensions.
@yield Instead of passing a module in namespace, you can provide
a block which returns your extension class. This gives you the ability to require other files only when the extension is first activated.
@return [void]