middleman-core 3.4.1 → 4.0.0.alpha.2

data/lib/middleman-core/core_extensions/routing.rb

@@ -1,70 +1,72 @@
 # Routing extension
 module Middleman
   module CoreExtensions
-    module Routing
-      # Takes a block which allows many pages to have the same layout
-      #
-      #   with_layout :admin do
-      #     page "/admin/"
-      #     page "/admin/login.html"
-      #   end
-      #
-      # @param [String, Symbol] layout_name
-      # @return [void]
-      def with_layout(layout_name, &block)
-        old_layout = config[:layout]
+    class Routing < Extension
+      # This should always run late, but not as late as :directory_indexes,
+      # so it can add metadata to any pages generated by other extensions
+      self.resource_list_manipulator_priority = 80
 
-        config[:layout] = layout_name
-        instance_exec(&block) if block_given?
-      ensure
-        config[:layout] = old_layout
+      def initialize(app, options_hash={}, &block)
+        super
+
+        @page_configs = Set.new
       end
 
-      # The page method allows the layout to be set on a specific path
+      def before_configuration
+        app.add_to_config_context(:page, &method(:page))
+      end
+
+      # @return Array<Middleman::Sitemap::Resource>
+      Contract ResourceList => ResourceList
+      def manipulate_resource_list(resources)
+        resources.each do |resource|
+          @page_configs.each do |p|
+            resource.add_metadata(p[:metadata]) if Middleman::Util.path_match(p[:path], "/#{resource.path}")
+          end
+        end
+      end
+
+      PageDescriptor = Struct.new(:path, :metadata)
+
+      # The page method allows options to be set for a given source path, regex, or glob.
+      # Options that may be set include layout, locals, proxy, andx ignore.
       #
-      #   page "/about.html", :layout => false
-      #   page "/", :layout => :homepage_layout
+      # @example
+      #   page '/about.html', layout: false
+      # @example
+      #   page '/index.html', layout: :homepage_layout
+      # @example
+      #   page '/foo.html', locals: { foo: 'bar' }
       #
-      # @param [String] url
-      # @param [Hash] opts
+      # @param [String, Regexp] path A source path, or a Regexp/glob that can match multiple resources.
+      # @params [Hash] opts Options to apply to all matching resources. Undocumented options are passed on as page metadata to be used by extensions.
+      # @option opts [Symbol, Boolean, String] layout The layout name to use (e.g. `:article`) or `false` to disable layout.
+      # @option opts [Boolean] directory_indexes Whether or not the `:directory_indexes` extension applies to these paths.
+      # @option opts [Hash] locals Local variables for the template. These will be available when the template renders.
+      # @option opts [Hash] data Extra metadata to add to the page. This is the same as frontmatter, though frontmatter will take precedence over metadata defined here. Available via {Resource#data}.
       # @return [void]
-      def page(url, opts={}, &block)
-        blocks = Array(block)
+      Contract String, Hash => Any
+      def page(path, opts={})
+        options = opts.dup
 
         # Default layout
-        opts[:layout] = config[:layout] if opts[:layout].nil?
+        metadata = {
+          options: options,
+          locals: options.delete(:locals) || {},
+          page: options.delete(:data) || {}
+        }
 
-        # If the url is a regexp
-        if url.is_a?(Regexp) || url.include?('*')
-
-          # Use the metadata loop for matching against paths at runtime
-          sitemap.provides_metadata_for_path(url) do |_|
-            { options: opts, blocks: blocks }
+        if path.is_a?(String) && !path.include?('*')
+          # Normalize path
+          path = Middleman::Util.normalize_path(path)
+          if path.end_with?('/') || app.files.by_type(:source).watchers.any? { |w| (w.directory + Pathname(path)).directory? }
+            path = File.join(path, @app.config[:index_file])
           end
-
-          return
         end
 
-        # Normalized path
-        url = '/' + Middleman::Util.normalize_path(url)
-        if url.end_with?('/') || File.directory?(File.join(source_dir, url))
-          url = File.join(url, config[:index_file])
-        end
-
-        # Setup proxy
-        if target = opts.delete(:proxy)
-          # TODO: deprecate proxy through page?
-          proxy(url, target, opts, &block)
-          return
-        elsif opts.delete(:ignore)
-          # TODO: deprecate ignore through page?
-          ignore(url)
-        end
+        path = '/' + Util.strip_leading_slash(path) if path.is_a?(String)
 
-        # Setup a metadata matcher for rendering those options
-        sitemap.provides_metadata_for_path(url) do |_|
-          { options: opts, blocks: blocks }
-        end
+        @page_configs << PageDescriptor.new(path, metadata)
       end
     end
   end

data/lib/middleman-core/core_extensions/show_exceptions.rb

@@ -1,25 +1,18 @@
-# Require lib
 require 'rack/showexceptions'
 
 # Support rack/showexceptions during development
-module Middleman
-  module CoreExtensions
-    module ShowExceptions
-      # Setup extension
-      class << self
-        # Once registered
-        def registered(app)
-          # Whether to catch and display exceptions
-          # @return [Boolean]
-          app.config.define_setting :show_exceptions, true, 'Whether to catch and display exceptions'
+module Middleman::CoreExtensions
+  class ShowExceptions < ::Middleman::Extension
+    def initialize(app, options_hash={}, &block)
+      super
 
-          # When in dev
-          app.configure :development do
-            # Include middleware
-            use ::Rack::ShowExceptions if config[:show_exceptions]
-          end
-        end
-      end
+      return if app.config.defines_setting? :show_exceptions
+
+      app.config.define_setting :show_exceptions, !!ENV['TEST'], 'Whether to catch and display exceptions'
+    end
+
+    def after_configuration
+      app.use ::Rack::ShowExceptions if app.config[:show_exceptions]
     end
   end
 end

data/lib/middleman-core/extension.rb

@@ -1,80 +1,196 @@
-require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/class/attribute'
 require 'middleman-core/configuration'
+require 'middleman-core/contracts'
 
 module Middleman
+  # 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}
+  #
+  # 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
   class Extension
+    extend Forwardable
+    include Contracts
+
+    def_delegator :@app, :logger
+
+    # @!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.
     class_attribute :supports_multiple_instances, instance_reader: false, instance_writer: false
+
+    # @!attribute defined_helpers
+    #   @!scope class
+    #   @api private
+    #   @return [Array<Module>] a list of all the helper modules this extension provides. Set these using {#helpers}.
     class_attribute :defined_helpers, instance_reader: false, instance_writer: false
+
+    # @!attribute ext_name
+    #   @!scope class
+    #   @return [Symbol] the name this extension is registered under. This is the symbol used to activate the extension.
     class_attribute :ext_name, instance_reader: false, instance_writer: false
 
+    # @!attribute resource_list_manipulator_priority
+    #   @!scope class
+    #   @return [Numeric] the priority for this extension's `manipulate_resource_list` method, if it has one.
+    #   @see Middleman::Sitemap::Store#register_resource_list_manipulator
+    class_attribute :resource_list_manipulator_priority, instance_reader: false, instance_writer: false
+
     class << self
+      # @api private
+      # @return [Middleman::Configuration::ConfigurationManager] The defined options for this extension.
       def config
         @_config ||= ::Middleman::Configuration::ConfigurationManager.new
       end
 
-      def option(key, default=nil, description=nil)
-        config.define_setting(key, default, description)
+      # 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
+      def option(key, default=nil, description=nil, options={})
+        config.define_setting(key, default, description, options)
       end
 
-      # Add helpers to the global Middleman application.
+      # 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.
-      def helpers(*m, &block)
+      # @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)
         self.defined_helpers ||= []
 
         if block_given?
           mod = Module.new
           mod.module_eval(&block)
-          m = [mod]
+          modules = [mod]
         end
 
-        self.defined_helpers += m
-      end
-
-      def extension_name
-        ext_name || name.underscore.split('/').last.to_sym
-      end
-
-      def register(n=extension_name)
-        ::Middleman::Extensions.register(n, self)
-      end
-
-      def activate
-        new(::Middleman::Application)
+        self.defined_helpers += modules
       end
 
+      # Reset all {Extension.after_extension_activated} callbacks.
+      # @api private
+      # @return [void]
       def clear_after_extension_callbacks
         @_extension_activation_callbacks = {}
       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]
       def after_extension_activated(name, &block)
         @_extension_activation_callbacks ||= {}
         @_extension_activation_callbacks[name] ||= []
         @_extension_activation_callbacks[name] << block if block_given?
       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]
       def activated_extension(instance)
-        name = instance.class.extension_name
-        return unless @_extension_activation_callbacks && @_extension_activation_callbacks[name]
+        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
     end
 
-    attr_accessor :options
-    attr_reader :app
+    # @return [Middleman::Configuration::ConfigurationManager] options for this extension instance.
+    attr_reader :options
 
-    delegate :after_extension_activated, to: :"::Middleman::Extension"
+    # @return [Middleman::Application] the Middleman application instance.
+    attr_reader :app
 
-    def initialize(klass, options_hash={}, &block)
+    # @!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]
+    def_delegator :"::Middleman::Extension", :after_extension_activated
+
+    # 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
+    def initialize(app, options_hash={}, &block)
       @_helpers = []
-      @klass = klass
+      @app = app
 
       setup_options(options_hash, &block)
-      setup_app_reference_when_available
 
       # Bind app hooks to local methods
       bind_before_configuration
@@ -83,16 +199,37 @@ module Middleman
       bind_after_build
     end
 
-    def app=(app)
-      @app = app
-
-      (self.class.defined_helpers || []).each do |m|
-        app.class.send(:include, m)
-      end
-    end
-
-    protected
-
+    # @!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 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
+
+    # @yield An optional block that can be used to customize options before the extension is activated.
+    # @yieldparam Middleman::Configuration::ConfigurationManager] options Extension options
     def setup_options(options_hash)
       @options = self.class.config.dup
       @options.finalize!
@@ -102,36 +239,26 @@ module Middleman
       end
 
       yield @options if block_given?
-    end
 
-    def setup_app_reference_when_available
-      ext = self
-
-      @klass.initialized do
-        ext.app = self
-      end
+      @options.all_settings.each do |o|
+        next unless o.options[:required] && !o.value_set?
 
-      @klass.instance_available do
-        ext.app ||= self
+        logger.error "The `:#{o.key}` option of the `#{self.class.ext_name}` extension is required."
+        exit(1)
       end
     end
 
     def bind_before_configuration
-      ext = self
-      return unless ext.respond_to?(:before_configuration)
-
-      @klass.before_configuration do
-        ext.before_configuration
-      end
+      @app.before_configuration(&method(:before_configuration)) if respond_to?(:before_configuration)
     end
 
     def bind_after_configuration
       ext = self
-      @klass.after_configuration do
+      @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_manipulator(ext.class.extension_name, ext)
+          ext.app.sitemap.register_resource_list_manipulator(ext.class.ext_name, ext, ext.class.resource_list_manipulator_priority)
         end
       end
     end
@@ -140,7 +267,7 @@ module Middleman
       ext = self
       return unless ext.respond_to?(:before_build)
 
-      @klass.before_build do |builder|
+      @app.before_build do |builder|
         if ext.method(:before_build).arity == 1
           ext.before_build(builder)
         else
@@ -153,7 +280,7 @@ module Middleman
       ext = self
       return unless ext.respond_to?(:after_build)
 
-      @klass.after_build do |builder|
+      @app.after_build do |builder|
         if ext.method(:after_build).arity == 1
           ext.after_build(builder)
         else