class Middleman::Extension

@see middlemanapp.com/advanced/custom/ Middleman Custom Extensions Documentation

Attributes

app[R]

@return [Middleman::Application] the Middleman application instance.

options[R]

@return [Middleman::Configuration::ConfigurationManager] options for this extension instance.

Public Class Methods

activated_extension(instance) click to toggle source

Notify that a particular extension has been activated and run all registered {Extension.after_extension_activated} callbacks. @api private @param [Middleman::Extension] instance Activated extension instance @return [void]

# 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) click to toggle source

Register to run a block after a named extension is activated. @param [Symbol] name The name the extension was registered under @param [Proc] block A callback to run when the named extension is activated @return [void]

# 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() click to toggle source

Reset all {Extension.after_extension_activated} callbacks. @api private @return [void]

# File lib/middleman-core/extension.rb, line 263
def clear_after_extension_callbacks
  @_extension_activation_callbacks = {}
end
config() click to toggle source

@api private @return [Middleman::Configuration::ConfigurationManager] The defined options for this extension.

# File lib/middleman-core/extension.rb, line 126
def config
  @_config ||= ::Middleman::Configuration::ConfigurationManager.new
end
define_setting(key, default=nil, description=nil, options={}) click to toggle source

Add an global option to this extension. @see Middleman::Configuration::ConfigurationManager#define_setting @example

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

@param [Symbol] key The name of the option @param [Object] default The default value for the option @param [String] description A human-readable description of what the option does

# 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) click to toggle source

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. @example with Hash:

expose_to_application global_name: :local_name

@example with Array:

expose_to_application :method1, :method2

@param [Array<Sumbol>, Hash<Symbol, Symbol>] symbols An optional list of symbols representing instance methods to exposed. @return [void]

# 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) click to toggle source

Takes a method within this extension and exposes it inside the scope of the config.rb sandbox. @example with Hash:

expose_to_config global_name: :local_name

@example with Array:

expose_to_config :method1, :method2

@param [Array<Sumbol>, Hash<Symbol, Symbol>] symbols An optional list of symbols representing instance methods to exposed. @return [void]

# 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) click to toggle source

Takes a method within this extension and exposes it inside the scope of the templating engine. Like ‘helpers`, but scoped. @example with Hash:

expose_to_template global_name: :local_name

@example with Array:

expose_to_template :method1, :method2

@param [Array<Sumbol>, Hash<Symbol, Symbol>] symbols An optional list of symbols representing instance methods to exposed. @return [void]

# 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_config() click to toggle source

@api private @return [Middleman::Configuration::ConfigurationManager] The defined global options for this extension.

# File lib/middleman-core/extension.rb, line 143
def global_config
  @_global_config ||= ::Middleman::Configuration::ConfigurationManager.new
end
helpers(*modules, &block) click to toggle source

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. @example With a block:

helpers do
  def my_helper
    "I helped!"
  end
end

@example With modules:

helpers FancyHelpers, PlainHelpers

@param [Array<Module>] modules An optional list of modules to add as helpers @param [Proc] block A block which will be evaluated to create a new helper module @return [void]

# 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
new(app, options_hash={}, &block) click to toggle source

Extensions are instantiated when they are activated. @param [Middleman::Application] app The Middleman::Application instance @param [Hash] options_hash The raw options hash. Subclasses should not manipulate this directly - it will be turned into {#options}. @yield An optional block that can be used to customize options before the extension is activated. @yieldparam [Middleman::Configuration::ConfigurationManager] options Extension options

# 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
option(key, default=nil, description=nil, options={}) click to toggle source

Add an option to this extension. @see Middleman::Configuration::ConfigurationManager#define_setting @example

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

@param [Symbol] key The name of the option @param [Object] default The default value for the option @param [String] description A human-readable description of what the option does

# 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) click to toggle source

Short-hand for simple Sitemap manipulation @example A generator which returns an array of resources

resources :make_resources

@example A generator which maps a path to a method

resources make_resource: :make_it

@example A generator which maps a path to a string

resources make_resource: 'Hello'

@param [Array] generators The generator definitions

# File lib/middleman-core/extension.rb, line 166
def resources(*generators)
  self.resources_generators ||= []
  self.resources_generators += generators
end

Public Instance Methods

add_exposed_to_context(context) click to toggle source

@!method manipulate_resource_list(resources)

Manipulate the resource list by transforming or adding {Sitemap::Resource}s.
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.
@note This method *must* return the full set of resources, because its return value will be used as the new sitemap.
@see http://middlemanapp.com/advanced/sitemap/ Sitemap Documentation
@see Sitemap::Store
@see Sitemap::Resource
@param [Array<Sitemap::Resource>] resources A list of all the resources known to the sitemap.
@return [Array<Sitemap::Resource>] The transformed list of resources.
# 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

Private Instance Methods

bind_after_build() click to toggle source
# File lib/middleman-core/extension.rb, line 473
def bind_after_build
  ext = self
  return unless ext.respond_to?(:after_build)

  @app.after_build do |builder|
    if ext.method(:after_build).arity == 1
      ext.after_build(builder)
    elsif ext.method(:after_build).arity == 2
      ext.after_build(builder, builder.thor)
    else
      ext.after_build
    end
  end
end
bind_after_configuration() click to toggle source
# File lib/middleman-core/extension.rb, line 401
def bind_after_configuration
  ext = self

  @app.after_configuration do
    ext.after_configuration if ext.respond_to?(:after_configuration)

    if ext.respond_to?(:manipulate_resource_list)
      ext.app.sitemap.register_resource_list_manipulators(ext.class.ext_name, ext, ext.class.resource_list_manipulator_priority)
    end

    if ext.class.resources_generators && !ext.class.resources_generators.empty?
      ext.app.sitemap.register_resource_list_manipulators(
        :"#{ext.class.ext_name}_generator",
        ext,
        ext.class.resource_list_manipulator_priority,
        :generate_resources
      )
    end
  end
end
bind_before_build() click to toggle source
# File lib/middleman-core/extension.rb, line 460
def bind_before_build
  ext = self
  return unless ext.respond_to?(:before_build)

  @app.before_build do |builder|
    if ext.method(:before_build).arity == 1
      ext.before_build(builder)
    else
      ext.before_build
    end
  end
end
bind_before_configuration() click to toggle source
# File lib/middleman-core/extension.rb, line 397
def bind_before_configuration
  @app.before_configuration(&method(:before_configuration)) if respond_to?(:before_configuration)
end
bind_ready() click to toggle source
# File lib/middleman-core/extension.rb, line 488
def bind_ready
  @app.ready(&method(:ready)) if respond_to?(:ready)
end
expose_methods() click to toggle source
# File lib/middleman-core/extension.rb, line 363
def expose_methods
  (self.class.exposed_to_application || {}).each do |k, v|
    app.define_singleton_method(k, &method(v))
  end

  (self.class.exposed_to_config || {}).each do |k, v|
    app.config_context.define_singleton_method(k, &method(v))
  end

  (self.class.defined_helpers || []).each do |m|
    app.template_context_class.send(:include, m)
  end
end
generate_resources(resources) click to toggle source
# File lib/middleman-core/extension.rb, line 422
def generate_resources(resources)
  generator_defs = self.class.resources_generators.reduce({}) do |sum, g|
    resource_definitions = if g.is_a? Hash
      g
    elsif g.is_a? Symbol
      definition = method(g)

      if definition.arity == 0
        send(g)
      else
        send(g, resources)
      end
    else
      {}
    end

    sum.merge!(resource_definitions)
  end

  resources + generator_defs.map do |path, g|
    if g.is_a? Symbol
      definition = method(g)

      g = if definition.arity == 0
        send(g)
      else
        send(g, resources)
      end
    end

    ::Middleman::Sitemap::StringResource.new(
      app.sitemap,
      path,
      g
    )
  end
end
setup_options(options_hash) { |options, self| ... } click to toggle source

@yield An optional block that can be used to customize options before the extension is activated. @yieldparam Middleman::Configuration::ConfigurationManager] options Extension options

# File lib/middleman-core/extension.rb, line 379
def setup_options(options_hash)
  @options = self.class.config.dup
  @options.finalize!

  options_hash.each do |k, v|
    @options[k] = v
  end

  yield @options, self if block_given?

  @options.all_settings.each do |o|
    next unless o.options[:required] && !o.value_set?

    logger.error "The `:#{o.key}` option of the `#{self.class.ext_name}` extension is required."
    exit(1)
  end
end