Class: Middleman::Extension

Inherits:
Object
  • Object
show all
Extended by:
Forwardable, Memoist
Includes:
Contracts
Defined in:
middleman-core/lib/middleman-core/extension.rb

Overview

Constant Summary

Constants included from Contracts

Contracts::ImmutableSetOf, Contracts::ImmutableSortedSetOf, Contracts::OldResourceList, Contracts::PATH_MATCHER, Contracts::ResourceList, Contracts::VectorOf

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Contracts

#Contract

Constructor Details

#initialize(app, options_hash = ::Middleman::EMPTY_HASH) {|options| ... } ⇒ Extension

Extensions are instantiated when they are activated.

Yields:

  • An optional block that can be used to customize options before the extension is activated.

Yield Parameters:


309
310
311
312
313
314
315
316
317
318
319
320
321
322
# File 'middleman-core/lib/middleman-core/extension.rb', line 309

def initialize(app, options_hash = ::Middleman::EMPTY_HASH, &block)
  @_helpers = []
  @app = app

  expose_methods
  setup_options(options_hash, &block)

  # Bind app hooks to local methods
  bind_before_configuration
  bind_after_configuration
  bind_before_build
  bind_after_build
  bind_ready
end

Class Attribute Details

.defined_helpersArray<Module>

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.

Returns a list of all the helper modules this extension provides. Set these using #helpers.


85
# File 'middleman-core/lib/middleman-core/extension.rb', line 85

class_attribute :defined_helpers, instance_reader: false, instance_writer: false

.exposed_to_applicationHash<Symbol, 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.

Returns a list of all the methods modules this extension exposes to app. Set these using #expose_to_application.


91
# File 'middleman-core/lib/middleman-core/extension.rb', line 91

class_attribute :exposed_to_application, instance_reader: false, instance_writer: false

.exposed_to_configHash<Symbol, 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.

Returns a list of all the methods modules this extension exposes to config. Set these using #expose_to_config.


97
# File 'middleman-core/lib/middleman-core/extension.rb', line 97

class_attribute :exposed_to_config, instance_reader: false, instance_writer: false

.exposed_to_templateArray<Any>

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.

Returns a list of method generators.


103
# File 'middleman-core/lib/middleman-core/extension.rb', line 103

class_attribute :exposed_to_template, instance_reader: false, instance_writer: false

.ext_nameSymbol


114
# File 'middleman-core/lib/middleman-core/extension.rb', line 114

class_attribute :ext_name, instance_reader: false, instance_writer: false

.resource_list_manipulator_priorityNumeric

Returns the priority for this extension's manipulate_resource_list method, if it has one.


120
# File 'middleman-core/lib/middleman-core/extension.rb', line 120

class_attribute :resource_list_manipulator_priority, instance_reader: false, instance_writer: false

.supports_multiple_instancesBoolean

By default extensions can only be activated once in a project. This is an advanced option.


79
# File 'middleman-core/lib/middleman-core/extension.rb', line 79

class_attribute :supports_multiple_instances, instance_reader: false, instance_writer: false

Instance Attribute Details

#appMiddleman::Application (readonly)


295
296
297
# File 'middleman-core/lib/middleman-core/extension.rb', line 295

def app
  @app
end

#optionsMiddleman::Configuration::ConfigurationManager (readonly)


292
293
294
# File 'middleman-core/lib/middleman-core/extension.rb', line 292

def options
  @options
end

Class Method Details

.activated_extension(instance)

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.

This method returns an undefined value.

Notify that a particular extension has been activated and run all registered after_extension_activated callbacks.


281
282
283
284
285
286
287
288
# File 'middleman-core/lib/middleman-core/extension.rb', line 281

def activated_extension(instance)
  name = instance.class.ext_name
  return unless @_extension_activation_callbacks&.key?(name)

  @_extension_activation_callbacks[name].each do |block|
    block.arity == 1 ? block.call(instance) : block.call
  end
end

.after_extension_activated(name, &block)

This method returns an undefined value.

Register to run a block after a named extension is activated.


270
271
272
273
274
# File 'middleman-core/lib/middleman-core/extension.rb', line 270

def after_extension_activated(name, &block)
  @_extension_activation_callbacks ||= {}
  @_extension_activation_callbacks[name] ||= []
  @_extension_activation_callbacks[name] << block if block_given?
end

.clear_after_extension_callbacks

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.

This method returns an undefined value.

Reset all after_extension_activated callbacks.


262
263
264
# File 'middleman-core/lib/middleman-core/extension.rb', line 262

def clear_after_extension_callbacks
  @_extension_activation_callbacks = {}
end

.configMiddleman::Configuration::ConfigurationManager

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.

Returns The defined options for this extension.


125
126
127
# File 'middleman-core/lib/middleman-core/extension.rb', line 125

def config
  @_config ||= ::Middleman::Configuration::ConfigurationManager.new
end

.define_setting(key, default = nil, description = nil, options_hash = ::Middleman::EMPTY_HASH) ⇒ Object

Add an global option to this extension.

Examples:

option :compress, false, 'Whether to compress the output'

See Also:


153
154
155
# File 'middleman-core/lib/middleman-core/extension.rb', line 153

def define_setting(key, default = nil, description = nil, options_hash = ::Middleman::EMPTY_HASH)
  global_config.define_setting(key, default, description, options_hash)
end

.expose_to_application(*symbols)

This method returns an undefined value.

Takes a method within this extension and exposes it globally on the main app instance. Used for very low-level extensions which many other extensions depend upon. Such as Data and File watching.

Examples:

with Hash:

expose_to_application global_name: :local_name

with Array:

expose_to_application :method1, :method2

207
208
209
210
211
212
213
214
215
216
217
# File 'middleman-core/lib/middleman-core/extension.rb', line 207

def expose_to_application(*symbols)
  self.exposed_to_application ||= {}

  if symbols.first&.is_a?(Hash)
    self.exposed_to_application.merge!(symbols.first)
  elsif symbols.is_a? Array
    symbols.each do |sym|
      self.exposed_to_application[sym] = sym
    end
  end
end

.expose_to_config(*symbols)

This method returns an undefined value.

Takes a method within this extension and exposes it inside the scope of the config.rb sandbox.

Examples:

with Hash:

expose_to_config global_name: :local_name

with Array:

expose_to_config :method1, :method2

227
228
229
230
231
232
233
234
235
236
237
# File 'middleman-core/lib/middleman-core/extension.rb', line 227

def expose_to_config(*symbols)
  self.exposed_to_config ||= {}

  if symbols.first&.is_a?(Hash)
    self.exposed_to_config.merge!(symbols.first)
  elsif symbols.is_a? Array
    symbols.each do |sym|
      self.exposed_to_config[sym] = sym
    end
  end
end

.expose_to_template(*symbols)

This method returns an undefined value.

Takes a method within this extension and exposes it inside the scope of the templating engine. Like helpers, but scoped.

Examples:

with Hash:

expose_to_template global_name: :local_name

with Array:

expose_to_template :method1, :method2

247
248
249
250
251
252
253
254
255
256
257
# File 'middleman-core/lib/middleman-core/extension.rb', line 247

def expose_to_template(*symbols)
  self.exposed_to_template ||= {}

  if symbols.first&.is_a?(Hash)
    self.exposed_to_template.merge!(symbols.first)
  elsif symbols.is_a? Array
    symbols.each do |sym|
      self.exposed_to_template[sym] = sym
    end
  end
end

.global_configMiddleman::Configuration::ConfigurationManager

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.

Returns The defined global options for this extension.


142
143
144
# File 'middleman-core/lib/middleman-core/extension.rb', line 142

def global_config
  @_global_config ||= ::Middleman::Configuration::ConfigurationManager.new
end

.helpers(*modules, &block)

This method returns an undefined value.

Declare helpers to be added the global Middleman application. This accepts either a list of modules to add on behalf of this extension, or a block whose contents will all be used as helpers in a new module.

Examples:

With a block:

helpers do
  def my_helper
    "I helped!"
  end
end

With modules:

helpers FancyHelpers, PlainHelpers

185
186
187
188
189
190
191
192
193
194
195
# File 'middleman-core/lib/middleman-core/extension.rb', line 185

def helpers(*modules, &block)
  self.defined_helpers ||= []

  if block_given?
    mod = Module.new
    mod.module_eval(&block)
    modules = [mod]
  end

  self.defined_helpers += modules
end

.option(key, default = nil, description = nil, options_hash = ::Middleman::EMPTY_HASH) ⇒ Object

Add an option to this extension.

Examples:

option :compress, false, 'Whether to compress the output'

See Also:


136
137
138
# File 'middleman-core/lib/middleman-core/extension.rb', line 136

def option(key, default = nil, description = nil, options_hash = ::Middleman::EMPTY_HASH)
  config.define_setting(key, default, description, options_hash)
end

.resources(*generators) ⇒ Object

Short-hand for simple Sitemap manipulation

Examples:

A generator which returns an array of resources

resources :make_resources

A generator which maps a path to a method

resources make_resource: :make_it

A generator which maps a path to a string

resources make_resource: 'Hello'

165
166
167
168
# File 'middleman-core/lib/middleman-core/extension.rb', line 165

def resources(*generators)
  self.resources_generators ||= []
  self.resources_generators += generators
end

Instance Method Details

#add_exposed_to_context(context) ⇒ Object


355
356
357
358
359
# File 'middleman-core/lib/middleman-core/extension.rb', line 355

def add_exposed_to_context(context)
  (self.class.exposed_to_template || {}).each do |k, v|
    context.define_singleton_method(k, &method(v))
  end
end

#after_buildObject

Respond to the after_build event. If an after_build method is implemented, that method will be run after the builder runs.


# File 'middleman-core/lib/middleman-core/extension.rb', line 337


#after_configurationObject

Respond to the after_configuration event. If an after_configuration method is implemented, that method will be run before config.rb is run.


# File 'middleman-core/lib/middleman-core/extension.rb', line 329


#after_extension_activated(name, &block)

This method returns an undefined value.

Register to run a block after a named extension is activated.


302
# File 'middleman-core/lib/middleman-core/extension.rb', line 302

def_delegator :"::Middleman::Extension", :after_extension_activated

#before_buildObject

Respond to the before_build event. If an before_build method is implemented, that method will be run before the builder runs.


# File 'middleman-core/lib/middleman-core/extension.rb', line 333


#before_configurationObject

Note:

Because most extensions are activated from within config.rb, they will not run any before_configuration hook.

Respond to the before_configuration event. If a before_configuration method is implemented, that method will be run before config.rb is run.


# File 'middleman-core/lib/middleman-core/extension.rb', line 324


#manipulate_resource_list(resources) ⇒ Array<Sitemap::Resource>

Note:

This method must return the full set of resources, because its return value will be used as the new sitemap.

Manipulate the resource list by transforming or adding Sitemap::Resources. Sitemap manipulation is a powerful way of interacting with a project, since it can modify each Sitemap::Resource or generate new Sitemap::Resources. This method is used in a pipeline where each sitemap manipulator is run in turn, with each one being fed the output of the previous manipulator. See the source of built-in Middleman extensions like Middleman::Extensions::DirectoryIndexes and Middleman::Extensions::AssetHash for examples of how to use this.


355
356
357
358
359
# File 'middleman-core/lib/middleman-core/extension.rb', line 355

def add_exposed_to_context(context)
  (self.class.exposed_to_template || {}).each do |k, v|
    context.define_singleton_method(k, &method(v))
  end
end

#readyObject

Respond to the ready event. If an ready method is implemented, that method will be run after the app has finished booting up.


# File 'middleman-core/lib/middleman-core/extension.rb', line 341