Module: Middleman::Extensions

Defined in:
middleman-core/lib/middleman-core/extensions.rb

Overview

The Extensions module is used to handle global registration and loading of Middleman Extensions.

The application-facing extension API (activate, etc) is in CoreExtensions::Extensions in middleman-core/core_extensions/extensions.rb.

Defined Under Namespace

Classes: AssetHash, AssetHost, AutoActivation, AutomaticImageSizes, CacheBuster, DirectoryIndexes, ExternalPipeline, Gzip, Lorem, MinifyCss, MinifyJavaScript, RelativeAssets

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.registered ⇒ Hash{Symbol => Class<Middleman::Extension>, Proc} (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A hash of all registered extensions. Registered extensions are not necessarily active - this is the set of all extensions that are known to Middleman.

Returns:

  • (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.


28
29
30
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 28

def registered
  @registered
end

Class Method Details

.auto_activate(group, app) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Load autoactivatable extensions for the given env.

Parameters:

  • group (Symbol) —

    The name of the auto_activation group.

  • app (Middleman::Application) —

    An instance of the app.


118
119
120
121
122
123
124
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 118

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

.auto_activated ⇒ Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A flattened list of all extensions which are automatically activated

Returns:

  • (Array<Symbol>) —

    A list of extension names which are automatically activated.


110
111
112
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 110

def auto_activated
  @auto_activate.values.map(&:to_a).flatten.map(&:name)
end

.load(name) ⇒ Class<Middleman::Extension>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Load an extension by name, lazily evaluating the block provided to #register if necessary.

Parameters:

  • name (Symbol) —

    The name of the extension

Returns:


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 88

def load(name)
  raise 'Extension name must be a symbol' unless name.is_a?(Symbol)

  raise "Unknown Extension: #{name}. Check the name and make sure you have referenced the extension's gem in your Gemfile." unless registered.key?(name)

  extension_class = registered[name]
  if extension_class.is_a?(Proc)
    extension_class = extension_class.call
    registered[name] = extension_class
  end

  raise "Tried to activate old-style extension: #{name}. They are no longer supported." unless extension_class.ancestors.include?(::Middleman::Extension)

  # Set the extension's name to whatever it was registered as.
  extension_class.ext_name = name

  extension_class
end

.load_settings(app) ⇒ Object 


126
127
128
129
130
131
132
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 126

def load_settings(app)
  registered.each do |name, _|
    ext = load(name)
    app.config.load_settings(ext.global_config.all_settings) unless ext.global_config.all_settings.empty?
  rescue LoadError
  end
end

.register(name, extension_class = nil, options_hash = ::Middleman::EMPTY_HASH) { ... }

This method returns an undefined value.

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

Parameters:

  • name (Symbol) —

    The name of the extension

  • extension_class (Class<Middleman::Extension>) (defaults to: nil) —

    The extension class (Must inherit from Middleman::Extension)

  • options (Hash) —

    a customizable set of options

Yields:

  • 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.


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'middleman-core/lib/middleman-core/extensions.rb', line 55

def register(name, extension_class = nil, options_hash = ::Middleman::EMPTY_HASH, &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)

  options = options_hash.dup

  # 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 && 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