Module: Middleman::Extensions

Defined in:
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, AutomaticAltTags, 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.



25
26
27
 
# File 'lib/middleman-core/extensions.rb', line 25

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.



116
117
118
119
120
121
122
 
# 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

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



108
109
110
 
# File 'lib/middleman-core/extensions.rb', line 108

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:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# 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

.load_settings(app) ⇒ Object 



124
125
126
127
128
129
130
131
132
133
134
 
# 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

.register(name, extension_class = nil, options = {}) { ... }

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) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :auto_activate (Boolean) —

    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.

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.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# 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