Class: Middleman::Extension

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

Overview

See Also:

Constant Summary

Constants included from Contracts

Contracts::PATH_MATCHER

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:



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

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_helpers ⇒ Array<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.



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

class_attribute :defined_helpers, instance_reader: false, instance_writer: false

.exposed_to_application ⇒ Hash<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.



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

class_attribute :exposed_to_application, instance_reader: false, instance_writer: false

.exposed_to_config ⇒ Hash<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.



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

class_attribute :exposed_to_config, instance_reader: false, instance_writer: false

.exposed_to_template ⇒ Array<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.



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

class_attribute :exposed_to_template, instance_reader: false, instance_writer: false

.ext_name ⇒ Symbol

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.



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

class_attribute :ext_name, instance_reader: false, instance_writer: false

.resource_list_manipulator_priority ⇒ Numeric

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:



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

class_attribute :resource_list_manipulator_priority, instance_reader: false, instance_writer: false

.supports_multiple_instances ⇒ Boolean

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.



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

class_attribute :supports_multiple_instances, instance_reader: false, instance_writer: false

Instance Attribute Details

#app ⇒ Middleman::Application (readonly)

Returns the Middleman application instance.

Returns:



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

def app
  @app
end

#options ⇒ Middleman::Configuration::ConfigurationManager (readonly)

Returns options for this extension instance.

Returns:



289
290
291
 
# File 'lib/middleman-core/extension.rb', line 289

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:



279
280
281
282
283
284
285
 
# File 'lib/middleman-core/extension.rb', line 279

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



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

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.



260
261
262
 
# File 'lib/middleman-core/extension.rb', line 260

def clear_after_extension_callbacks
  @_extension_activation_callbacks = {}
end

.config ⇒ Middleman::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:



123
124
125
 
# File 'lib/middleman-core/extension.rb', line 123

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:



151
152
153
 
# File 'lib/middleman-core/extension.rb', line 151

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.



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

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.



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

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.



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

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_config ⇒ Middleman::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:



140
141
142
 
# File 'lib/middleman-core/extension.rb', line 140

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



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

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:



134
135
136
 
# File 'lib/middleman-core/extension.rb', line 134

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



163
164
165
166
 
# File 'lib/middleman-core/extension.rb', line 163

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

Instance Method Details

#add_exposed_to_context(context) ⇒ Object 



352
353
354
355
356
 
# File 'lib/middleman-core/extension.rb', line 352

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_build ⇒ Object

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




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

#after_configuration ⇒ Object

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




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

#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



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

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

#before_build ⇒ Object

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




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

#before_configuration ⇒ Object

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 'lib/middleman-core/extension.rb', line 321

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



352
353
354
355
356
 
# File 'lib/middleman-core/extension.rb', line 352

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

#ready ⇒ Object

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




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