2014-02-23 03:46:32 +01:00
require 'active_support/core_ext/module/delegation'
2014-02-23 03:43:47 +01:00
require 'active_support/core_ext/class/attribute'
2014-02-23 03:46:32 +01:00
2014-01-01 23:50:42 +01:00
module Middleman
2014-05-11 08:47:04 +02:00
# Middleman's Extension API provides the ability to add functionality to Middleman
# and to customize existing features. Internally, most features in Middleman are
# implemented as extensions. A good way to figure out how to write your own extension
# is to look at the source of the built-in extensions or popular extension gems like
# `middleman-blog` or `middleman-syntax`.
#
# The most basic extension looks like:
#
# class MyFeature < Middleman::Extension
# def initialize(app, options_hash={}, &block)
# super
# end
# end
# ::Middleman::Extensions.register(:my_feature, MyFeature)
#
# A more complicated example might look like:
#
# class MyFeature < Middleman::Extension
# option :my_option, 'cool', 'A very cool option'
#
# def initialize(app, options_hash={}, &block)
# super
# puts "My option is #{options.my_option}"
# end
#
# def after_configuration
# puts "The project has been configured"
# end
#
# def manipulate_resource_list(resources)
# resources.each do |resource|
# # Make all .jpg's get built or served with a .jpeg extension.
# if resource.ext == '.jpg'
# resource.destination_path = resource.destination_path.sub('.jpg', '.jpeg')
# end
# end
# end
# end
#
# ::Middleman::Extensions.register :my_feature do
# MyFeature
# end
#
# Extensions can add helpers (via {Extension.helpers}), add to the sitemap or change it (via {#manipulate_resource_list}), or run
# arbitrary code at different parts of the Middleman application's lifecycle. They can have options (defined via {Extension.option} and accessed via {#options}).
#
# Common lifecycle events can be handled by extensions simply by implementing an appropriately-named method:
#
# * {#after_configuration}
# * {#after_build}
# * {#before_build}
# * {#instance_available}
#
# There are also some less common hooks that can be listened to from within an extension's `initialize` method:
#
# * `app.before_render {|body, path, locs, template_class| ... }` - Manipulate template sources before they are rendered.
# * `app.after_render {|content, path, locs, template_class| ... }` - Manipulate output text after a template has been rendered. It is also common to install a Rack middleware to do this instead.
# * `app.ready { ... }` - Run code once Middleman is ready to serve or build files (after `after_configuration`).
# * `app.compass_config { |compass_config| ... }` - Manipulate the Compass configuration after it has been set up.
#
# @see http://middlemanapp.com/advanced/custom/ Middleman Custom Extensions Documentation
2014-01-01 23:50:42 +01:00
class Extension
2014-05-11 08:47:04 +02:00
# @!attribute supports_multiple_instances
# @!scope class
# @return [Boolean] whether or not an extension can be activated multiple times, generating multiple instances of the extension.
# By default extensions can only be activated once in a project. This is an advanced option.
2014-04-29 19:50:21 +02:00
class_attribute :supports_multiple_instances , instance_reader : false , instance_writer : false
2014-05-11 08:47:04 +02:00
# @!attribute defined_helpers
# @!scope class
# @api private
# @return [Array<Module>] a list of all the helper modules this extension provides. Set these using {#helpers}.
2014-04-29 19:50:21 +02:00
class_attribute :defined_helpers , instance_reader : false , instance_writer : false
2014-05-11 08:47:04 +02:00
# @!attribute ext_name
# @!scope class
# @return [Symbol] the name this extension is registered under. This is the symbol used to activate the extension.
2014-04-29 19:50:21 +02:00
class_attribute :ext_name , instance_reader : false , instance_writer : false
2014-01-01 23:50:42 +01:00
class << self
2014-05-11 08:47:04 +02:00
# @api private
# @return [Middleman::Configuration::ConfigurationManager] The defined options for this extension.
2014-01-01 23:50:42 +01:00
def config
@_config || = :: Middleman :: Configuration :: ConfigurationManager . new
end
2014-05-11 08:47:04 +02:00
# 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
2014-01-01 23:50:42 +01:00
def option ( key , default = nil , description = nil )
config . define_setting ( key , default , description )
end
2014-05-11 08:47:04 +02:00
# Declare helpers to be added the global Middleman application.
2014-01-01 23:50:42 +01:00
# 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.
2014-05-11 08:47:04 +02:00
# @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]
def helpers ( * modules , & block )
2014-01-01 23:50:42 +01:00
self . defined_helpers || = [ ]
2014-01-02 06:19:05 +01:00
if block_given?
2014-01-01 23:50:42 +01:00
mod = Module . new
mod . module_eval ( & block )
2014-05-11 08:47:04 +02:00
modules = [ mod ]
2014-01-01 23:50:42 +01:00
end
2014-05-11 08:47:04 +02:00
self . defined_helpers += modules
2014-01-01 23:50:42 +01:00
end
2014-05-11 08:47:04 +02:00
# Reset all {Extension.after_extension_activated} callbacks.
# @api private
# @return [void]
2014-01-01 23:50:42 +01:00
def clear_after_extension_callbacks
@_extension_activation_callbacks = { }
end
2014-05-11 08:47:04 +02:00
# 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]
2014-01-01 23:50:42 +01:00
def after_extension_activated ( name , & block )
@_extension_activation_callbacks || = { }
@_extension_activation_callbacks [ name ] || = [ ]
@_extension_activation_callbacks [ name ] << block if block_given?
end
2014-05-11 08:47:04 +02:00
# 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]
2014-01-01 23:50:42 +01:00
def activated_extension ( instance )
2014-03-29 22:29:42 +01:00
name = instance . class . ext_name
2014-05-11 08:47:04 +02:00
return unless @_extension_activation_callbacks && @_extension_activation_callbacks . has_key? ( name )
2014-01-01 23:50:42 +01:00
@_extension_activation_callbacks [ name ] . each do | block |
2014-04-29 19:50:21 +02:00
block . arity == 1 ? block . call ( instance ) : block . call
2014-01-01 23:50:42 +01:00
end
end
end
2014-05-11 08:47:04 +02:00
# @return [Middleman::Configuration::ConfigurationManager] options for this extension instance.
attr_reader :options
# @return [Middleman::Application] the Middleman application instance.
2014-01-01 23:50:42 +01:00
attr_reader :app
2014-05-11 08:47:04 +02:00
# @!method after_extension_activated(name, &block)
# 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]
2014-04-29 19:50:21 +02:00
delegate :after_extension_activated , to : :" ::Middleman::Extension "
2014-01-01 23:50:42 +01:00
2014-05-11 08:47:04 +02:00
# Extensions are instantiated when they are activated.
# @param [Class] klass The Middleman::Application class
# @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
2014-01-01 23:50:42 +01:00
def initialize ( klass , options_hash = { } , & block )
@_helpers = [ ]
@klass = klass
setup_options ( options_hash , & block )
setup_app_reference_when_available
# Bind app hooks to local methods
bind_before_configuration
bind_after_configuration
2014-02-23 03:11:37 +01:00
bind_before_build
2014-01-01 23:50:42 +01:00
bind_after_build
end
2014-05-11 08:47:04 +02:00
# @!method before_configuration
# Respond to the `before_configuration` event.
# If a `before_configuration` method is implemented, that method will be run before `config.rb` is run.
# @note Because most extensions are activated from within `config.rb`, they *will not run* any `before_configuration` hook.
# @!method after_configuration
# Respond to the `after_configuration` event.
# If an `after_configuration` method is implemented, that method will be run before `config.rb` is run.
# @!method before_build
# Respond to the `before_build` event.
# If an `before_build` method is implemented, that method will be run before the builder runs.
# @!method after_build
# Respond to the `after_build` event.
# If an `after_build` method is implemented, that method will be run after the builder runs.
# @!method instance_available
# Respond to the `instance_available` event.
# If an `instance_available` method is implemented, that method will be run after `config.rb` is run and after environment-specific config blocks have been run, but before any `after_configuration` callbacks.
# @!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.
# Assign the app instance. Used internally.
# @api private
2014-01-01 23:50:42 +01:00
def app = ( app )
@app = app
2014-01-02 06:19:05 +01:00
ext = self
if ext . respond_to? ( :instance_available )
@klass . instance_available do
ext . instance_available
end
2014-01-01 23:50:42 +01:00
end
end
2014-05-11 05:16:37 +02:00
private
2014-01-01 23:50:42 +01:00
2014-05-11 08:47:04 +02:00
# @yield An optional block that can be used to customize options before the extension is activated.
# @yieldparam Middleman::Configuration::ConfigurationManager] options Extension options
2014-04-29 19:44:24 +02:00
def setup_options ( options_hash )
2014-01-01 23:50:42 +01:00
@options = self . class . config . dup
@options . finalize!
options_hash . each do | k , v |
@options [ k ] = v
end
yield @options if block_given?
end
def setup_app_reference_when_available
ext = self
@klass . initialized do
ext . app = self
end
@klass . instance_available do
ext . app || = self
end
end
def bind_before_configuration
ext = self
if ext . respond_to? ( :before_configuration )
@klass . before_configuration do
ext . before_configuration
end
end
end
def bind_after_configuration
ext = self
@klass . after_configuration do
2014-04-29 19:44:24 +02:00
ext . after_configuration if ext . respond_to? ( :after_configuration )
2014-01-01 23:50:42 +01:00
2014-04-29 19:44:24 +02:00
# rubocop:disable IfUnlessModifier
2014-01-01 23:50:42 +01:00
if ext . respond_to? ( :manipulate_resource_list )
2014-03-29 22:29:42 +01:00
ext . app . sitemap . register_resource_list_manipulator ( ext . class . ext_name , ext )
2014-01-01 23:50:42 +01:00
end
end
end
2014-02-23 03:11:37 +01:00
def bind_before_build
ext = self
if ext . respond_to? ( :before_build )
@klass . before_build do | builder |
2014-04-29 01:02:18 +02:00
if ext . method ( :before_build ) . arity == 1
2014-02-23 03:11:37 +01:00
ext . before_build ( builder )
else
ext . before_build
end
end
end
end
2014-01-01 23:50:42 +01:00
def bind_after_build
ext = self
if ext . respond_to? ( :after_build )
@klass . after_build do | builder |
2014-04-29 01:02:18 +02:00
if ext . method ( :after_build ) . arity == 1
2014-01-01 23:50:42 +01:00
ext . after_build ( builder )
else
ext . after_build
end
end
end
end
end
end