class Middleman::Extension
@see middlemanapp.com/advanced/custom/ Middleman
Custom Extensions
Documentation
Attributes
@return [Middleman::Configuration::ConfigurationManager] options for this extension instance.
Public Class Methods
Source
# 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
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]
Source
# 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
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]
Source
# File lib/middleman-core/extension.rb, line 263 def clear_after_extension_callbacks @_extension_activation_callbacks = {} end
Reset all {Extension.after_extension_activated} callbacks. @api private @return [void]
Source
# File lib/middleman-core/extension.rb, line 126 def config @_config ||= ::Middleman::Configuration::ConfigurationManager.new end
@api private @return [Middleman::Configuration::ConfigurationManager] The defined options for this extension.
Source
# 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
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
Source
# 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
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]
Source
# 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
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]
Source
# 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
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]
Source
# File lib/middleman-core/extension.rb, line 143 def global_config @_global_config ||= ::Middleman::Configuration::ConfigurationManager.new end
@api private @return [Middleman::Configuration::ConfigurationManager] The defined global options for this extension.
Source
# 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
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]
Source
# 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
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
Source
# File lib/middleman-core/extension.rb, line 137 def option(key, default=nil, description=nil, options={}) config.define_setting(key, default, description, options) end
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
Source
# File lib/middleman-core/extension.rb, line 166 def resources(*generators) self.resources_generators ||= [] self.resources_generators += generators end
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
Public Instance Methods
Source
# 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
@!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.
Private Instance Methods
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
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
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
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
Source
# File lib/middleman-core/extension.rb, line 488 def bind_ready @app.ready(&method(:ready)) if respond_to?(:ready) end
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
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
Source
# 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
@yield An optional block that can be used to customize options before the extension is activated. @yieldparam Middleman::Configuration::ConfigurationManager
] options Extension
options