Class: Middleman::Extension

Inherits:
Object
  • Object
show all
Extended by:
Forwardable, Memoist
Includes:
Contracts
Defined in:
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.

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

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.



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

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.



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

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.



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

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.



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

class_attribute :exposed_to_template, instance_reader: false, instance_writer: false

.ext_nameSymbol



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

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.



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

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.



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

class_attribute :supports_multiple_instances, instance_reader: false, instance_writer: false

Instance Attribute Details

#appMiddleman::Application (readonly)



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

def app
  @app
end

#optionsMiddleman::Configuration::ConfigurationManager (readonly)



292
293
294
# File '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.



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

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.



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

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.



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

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.



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

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'

See Also:



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

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


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

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


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

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


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

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.



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

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


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

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'

See Also:



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

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'


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

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