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::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 = {}) {|options| ... } ⇒ Extension

Extensions are instantiated when they are activated.

Parameters:

  • app (Middleman::Application)

    The Middleman::Application instance

  • options_hash (Hash) (defaults to: {})

    The raw options hash. Subclasses should not manipulate this directly - it will be turned into #options.

Yields:

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

Yield Parameters:



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

def initialize(app, options_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.

Returns:

  • (Array<Module>)

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



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

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.

Returns:

  • (Hash<Symbol, Symbol>)

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



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

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.

Returns:

  • (Hash<Symbol, Symbol>)

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



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

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.

Returns:

  • (Array<Any>)

    a list of method generators.



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

class_attribute :exposed_to_template, instance_reader: false, instance_writer: false

.ext_nameSymbol

Returns the name this extension is registered under. This is the symbol used to activate the extension.

Returns:

  • (Symbol)

    the name this extension is registered under. This is the symbol used to activate the extension.



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

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.

Returns:

  • (Numeric)

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

See Also:



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

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.

Returns:

  • (Boolean)

    whether or not an extension can be activated multiple times, generating multiple instances of the extension.



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

class_attribute :supports_multiple_instances, instance_reader: false, instance_writer: false

Instance Attribute Details

#appMiddleman::Application (readonly)

Returns the Middleman application instance.

Returns:



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

def app
  @app
end

#optionsMiddleman::Configuration::ConfigurationManager (readonly)

Returns options for this extension instance.

Returns:



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

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.

Parameters:



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

def activated_extension(instance)
  name = instance.class.ext_name
  return unless @_extension_activation_callbacks && @_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.

Parameters:

  • name (Symbol)

    The name the extension was registered under

  • block (Proc)

    A callback to run when the named extension is activated



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

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.



264
265
266
# File 'middleman-core/lib/middleman-core/extension.rb', line 264

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.

Returns:



127
128
129
# File 'middleman-core/lib/middleman-core/extension.rb', line 127

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

.define_setting(key, default = nil, description = nil, options = {}) ⇒ Object

Add an global option to this extension.

Examples:

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

Parameters:

  • key (Symbol)

    The name of the option

  • default (Object) (defaults to: nil)

    The default value for the option

  • description (String) (defaults to: nil)

    A human-readable description of what the option does

See Also:



155
156
157
# File 'middleman-core/lib/middleman-core/extension.rb', line 155

def define_setting(key, default=nil, description=nil, options={})
  global_config.define_setting(key, default, description, options)
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

Parameters:

  • symbols (Array<Sumbol>, Hash<Symbol, Symbol>)

    An optional list of symbols representing instance methods to exposed.



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

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

  if symbols.first && 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

Parameters:

  • symbols (Array<Sumbol>, Hash<Symbol, Symbol>)

    An optional list of symbols representing instance methods to exposed.



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

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

  if symbols.first && 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

Parameters:

  • symbols (Array<Sumbol>, Hash<Symbol, Symbol>)

    An optional list of symbols representing instance methods to exposed.



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

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

  if symbols.first && 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.

Returns:



144
145
146
# File 'middleman-core/lib/middleman-core/extension.rb', line 144

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

Parameters:

  • modules (Array<Module>)

    An optional list of modules to add as helpers

  • block (Proc)

    A block which will be evaluated to create a new helper module



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

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 = {}) ⇒ Object

Add an option to this extension.

Examples:

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

Parameters:

  • key (Symbol)

    The name of the option

  • default (Object) (defaults to: nil)

    The default value for the option

  • description (String) (defaults to: nil)

    A human-readable description of what the option does

See Also:



138
139
140
# File 'middleman-core/lib/middleman-core/extension.rb', line 138

def option(key, default=nil, description=nil, options={})
  config.define_setting(key, default, description, options)
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'

Parameters:

  • generators (Array)

    The generator definitions



167
168
169
170
# File 'middleman-core/lib/middleman-core/extension.rb', line 167

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

Instance Method Details

#add_exposed_to_context(context) ⇒ Object



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

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 338

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

#after_extension_activated(name, &block)

This method returns an undefined value.

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

Parameters:

  • name (Symbol)

    The name the extension was registered under

  • block (Proc)

    A callback to run when the named extension is activated



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

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 334

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

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

Parameters:

Returns:

See Also:



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

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 342