middleman-blog 3.4.1 → 3.5.0

data/lib/middleman-blog/helpers.rb

@@ -0,0 +1,152 @@
+module Middleman
+  module Blog
+    # Blog-related helpers that are available to the Middleman application in +config.rb+ and in templates.
+    module Helpers
+      # All the blog instances known to this Middleman app, keyed by name. A new blog is added
+      # every time the blog extension is activated. Name them by setting the +:name+
+      # option when activating - otherwise they get an automatic name like 'blog0', 'blog1', etc.
+      #
+      # @return [Hash<Symbol,BlogExtension>] a hash of all blog instances by name
+      def blog_instances
+        @blog_instances ||= {}
+      end
+
+      # Retrieve a {BlogExtension} instance.
+      # If +blog_name+ is provided, the instance with that name will be returned.
+      # Otherwise, an attempt is made to find the appropriate blog controller
+      # for the current resource. For articles this is always available, but
+      # for other pages it may be necessary to name the blog in frontmatter
+      # using the "blog" blog_name. If there is only one blog, this method will
+      # always return that blog.
+      #
+      # @param [Symbol, String] blog_name Optional name of the blog to get a controller for.
+      # @return [BlogExtension]
+      def blog_controller(blog_name=nil)
+        if !blog_name && current_resource
+          blog_name = current_resource.metadata[:page]["blog"]
+
+          if !blog_name
+            blog_controller = current_resource.blog_controller if current_resource.respond_to?(:blog_controller)
+            return blog_controller if blog_controller
+          end
+        end
+
+        # In multiblog situations, force people to specify the blog
+        if !blog_name && blog_instances.size > 1
+          raise "You must either specify the blog name in calling this method or in your page frontmatter (using the 'blog' blog_name)"
+        end
+
+        blog_name ||= blog_instances.keys.first
+        blog_instances[blog_name.to_sym]
+      end
+
+      # Get a {BlogData} instance for the given blog. Follows the
+      # same rules as {#blog_controller}.
+      #
+      # @param [Symbol, String] blog_name Optional name of the blog to get data for.
+      #   Blogs can be named as an option or will default to 'blog0', 'blog1', etc..
+      # @return [BlogData]
+      def blog(blog_name=nil)
+        blog_controller(blog_name).data
+      end
+
+      # Determine whether the currently rendering template is a {BlogArticle}.
+      # This can be useful in layouts and helpers.
+      # @return [Boolean]
+      def is_blog_article?
+        !current_article.nil?
+      end
+
+      # Get a {BlogArticle} representing the current article.
+      # @return [BlogArticle]
+      def current_article
+        article = current_resource
+        if article && article.is_a?(BlogArticle)
+          article
+        else
+          nil
+        end
+      end
+
+      # Get a path to the given tag page, based on the +taglink+ blog setting.
+      # @param [String] tag
+      # @param [Symbol, String] blog_name Optional name of the blog to use.
+      # @return [String]
+      def tag_path(tag, blog_name=nil)
+        build_url blog_controller(blog_name).tag_pages.link(tag)
+      end
+
+      # Get a path to the given year-based calendar page, based on the +year_link+ blog setting.
+      # @param [Number] year
+      # @param [Symbol, String] blog_name Optional name of the blog to use.
+      # @return [String]
+      def blog_year_path(year, blog_name=nil)
+        build_url blog_controller(blog_name).calendar_pages.link(year)
+      end
+
+      # Get a path to the given month-based calendar page, based on the +month_link+ blog setting.
+      # @param [Number] year
+      # @param [Number] month
+      # @param [Symbol, String] blog_name Optional name of the blog to use.
+      # @return [String]
+      def blog_month_path(year, month, blog_name=nil)
+        build_url blog_controller(blog_name).calendar_pages.link(year, month)
+      end
+
+      # Get a path to the given day-based calendar page, based on the +day_link+ blog setting.
+      # @param [Number] year
+      # @param [Number] month
+      # @param [Number] day
+      # @param [Symbol, String] blog_name Optional name of the blog to use.
+      # @return [String]
+      def blog_day_path(year, month, day, blog_name=nil)
+        build_url blog_controller(blog_name).calendar_pages.link(year, month, day)
+      end
+
+      # Whether or not pagination is enabled for this template. This can be used
+      # to allow a single template to work in both paginating and non-paginating modes.
+      # @return [Boolean]
+      def paginate
+        false
+      end
+
+      # Returns the list of articles to display on this particular page (when using pagination).
+      # @param [Symbol, String] blog_name Optional name of the blog to use.
+      # @return [Array<Middleman::Sitemap::Resource>]
+      def page_articles(blog_name=nil)
+        meta = current_resource.metadata
+        limit = meta[:page]["per_page"]
+
+        # "articles" local variable is populated by Calendar and Tag page generators
+        # If it's not set then use the complete list of articles
+        articles = meta[:locals]["articles"] || blog(blog_name).articles
+
+        limit ? articles.first(limit) : articles
+      end
+
+      # Generate helpers to access the path to a custom collection.
+      #
+      # For example, when using a custom property called "category" to collect articles on
+      # the method **category_path** will be generated.
+      #
+      # @param [Symbol] property Custom property which is being used to collect articles on
+      # @private
+      def self.generate_custom_helper(property)
+        define_method :"#{property}_path" do |value, blog_name=nil|
+          custom_pages = blog_controller(blog_name).custom_pages
+
+          if !custom_pages.key?(property)
+            raise "This blog does not know about the custom property #{property.inspect}"
+          end
+          build_url custom_pages[property].link(value)
+        end
+      end
+
+      private
+
+      def build_url(path)
+        sitemap.find_resource_by_path(path).try(:url)
+      end
+    end
+  end
+end

data/lib/middleman-blog/paginator.rb

@@ -1,38 +1,149 @@
+require 'middleman-blog/uri_templates'
+
 module Middleman
   module Blog
-
     # A sitemap plugin that splits indexes (including tag
     # and calendar indexes) over multiple pages
     class Paginator
-      def initialize(app, controller=nil)
+      include UriTemplates
+
+      def initialize(app, blog_controller)
         @app = app
-        @blog_controller = controller
+        @blog_controller = blog_controller
+        @per_page = blog_controller.options.per_page
+        @page_link = blog_controller.options.page_link
       end
 
-      def blog_data
-        if @blog_controller
-          @blog_controller.data
-        else
-          @app.blog
+      # Update the main sitemap resource list
+      # @return [void]
+      def manipulate_resource_list(resources)
+        new_resources = []
+
+        resources.each do |res|
+          next if res.ignored?
+
+          # Avoid recomputing metadata over and over
+          md = res.metadata
+
+          next unless md[:page]["pageable"]
+
+          # Skip other blogs' resources
+          next unless match_blog(res, md)
+
+          # "articles" local variable is populated by Calendar and Tag page generators
+          # If it's not set then use the complete list of articles
+          # TODO: Some way to allow the frontmatter to specify the article filter?
+          articles = md[:locals]["articles"] || @blog_controller.data.articles
+
+          # Allow blog.per_page and blog.page_link to be overridden in the frontmatter
+          per_page  = md[:page]["per_page"] || @per_page
+          page_link = uri_template(md[:page]["page_link"] || @page_link)
+
+          num_pages = (articles.length / per_page.to_f).ceil
+
+          # Add the pagination metadata to the base page (page 1)
+          res.add_metadata locals: page_locals(1, num_pages, per_page, nil, articles)
+
+          prev_page_res = res
+
+          # Create additional resources for the 2nd and subsequent pages.
+          2.upto(num_pages) do |page_num|
+            p = page_resource(res, page_num, page_link)
+
+            # Copy the metadata from the base page
+            p.add_metadata md
+            p.add_metadata locals: page_locals(page_num, num_pages, per_page, prev_page_res, articles)
+
+            # Add a reference in the previous page to this page
+            prev_page_res.add_metadata locals: { 'next_page' => p }
+
+            prev_page_res = p
+
+            new_resources << p
+          end
         end
+
+        resources + new_resources
       end
 
-      def blog_options
-        if @blog_controller
-          @blog_controller.options
-        else
-          @app.blog.options
+      private
+
+      # Does this resource match the blog controller for this paginator?
+      # @return [Boolean]
+      def match_blog(res, md)
+        res_controller = md[:locals]["blog_controller"] || (res.respond_to?(:blog_controller) && res.blog_controller)
+        return false if res_controller && res_controller != @blog_controller
+        override_controller = md[:page]["blog"]
+        return false if override_controller && override_controller.to_s != @blog_controller.name.to_s
+
+        true
+      end
+
+      # Generate a resource for a particular page
+      # @param [Sitemap::Resource] res the original resource
+      # @param [Integer] page_num the page number to generate a resource for
+      # @param [String] page_link The pagination link path component template
+      def page_resource(res, page_num, page_link)
+        path = page_sub(res, page_num, page_link)
+        Sitemap::Resource.new(@app.sitemap, path, res.source_file).tap do |p|
+          # Copy the proxy state from the base page.
+          p.proxy_to(res.proxied_to) if res.proxy?
         end
       end
 
+      # @param [Integer] page_num the page number to generate a resource for
+      # @param [Integer] num_pages Total number of pages
+      # @param [Integer] per_page How many articles per page
+      # @param [Sitemap::Resource] prev_page_res The resource of the previous page
+      # @param [Array<Sitemap::Resource>] articles The list of all articles
+      def page_locals(page_num, num_pages, per_page, prev_page_res, articles)
+        # Index into articles of the first article of this page
+        page_start = (page_num - 1) * per_page
+
+        # Index into articles of the last article of this page
+        page_end = (page_num * per_page) - 1
+
+        {
+          # Set a flag to allow templates to be used with and without pagination
+          'paginate' => true,
+
+          # Include the numbers, useful for displaying "Page X of Y"
+          'page_number' => page_num,
+          'num_pages' => num_pages,
+          'per_page' => per_page,
+
+          # The range of article numbers on this page
+          # (1-based, for showing "Items X to Y of Z")
+          'page_start' => page_start + 1,
+          'page_end' => [page_end + 1, articles.length].min,
+
+          # These contain the next and previous page.
+          # They are set to nil if there are no more pages.
+          # The nils are overwritten when the later pages are generated, below.
+          'next_page' => nil,
+          'prev_page' => prev_page_res,
+
+          # The list of articles for this page.
+          'page_articles' => articles[page_start..page_end],
+
+          # Include the articles so that non-proxied pages can use "articles" instead
+          # of "blog.articles" for consistency with the calendar and tag templates.
+          'articles' => articles,
+          'blog_controller' => @blog_controller
+        }
+      end
+
       # Substitute the page number into the resource URL.
+      # @param [Middleman::Sitemap::Resource] res The resource to generate pages for
+      # @param [Integer] page_num The page page_number
+      # @param [String] page_link The pagination link path component template
       # @return [String]
-      def page_sub(res, num, page_link)
-        if num == 1
+      def page_sub(res, page_num, page_link)
+        if page_num == 1
           # First page has an unmodified URL.
           res.path
         else
-          page_url = page_link.sub(":num", num.to_s)
+          page_url = apply_uri_template page_link, num: page_num
           index_re = %r{(^|/)#{Regexp.escape(@app.index_file)}$}
           if res.path =~ index_re
             res.path.sub(index_re, "\\1#{page_url}/#{@app.index_file}")
@@ -41,113 +152,6 @@ module Middleman
           end
         end
       end
-
-      # Update the main sitemap resource list
-      # @return [void]
-      def manipulate_resource_list(resources)
-        new_resources = []
-
-        resources.each do |res|
-          next if res.ignored?
-
-          md = res.metadata
-
-          # Skip other blogs' resources
-          res_controller = md[:locals]["blog_controller"] || (res.respond_to?(:blog_controller) && res.blog_controller)
-          next if @blog_controller && res_controller && (res_controller != @blog_controller)
-          override_controller = md[:page]["blog"]
-          next if @blog_controller && override_controller && override_controller != @blog_controller.uid
-
-          if md[:page]["pageable"]
-            # "articles" local variable is populated by Calendar and Tag page generators
-            # If it's not set then use the complete list of articles
-            # TODO: Some way to allow the frontmatter to specify the article filter?
-            articles = md[:locals]["articles"] || self.blog_data.articles
-
-            # Allow blog.per_page and blog.page_link to be overridden in the frontmatter
-            per_page  = md[:page]["per_page"] || self.blog_options.per_page
-            page_link = md[:page]["page_link"] || self.blog_options.page_link
-
-            num_pages = (articles.length / per_page.to_f).ceil
-
-            # Add the pagination metadata to the base page (page 1)
-            res.add_metadata :locals => {
-              # Set a flag to allow templates to be used with and without pagination
-              'paginate' => true,
-
-              # Include the numbers, useful for displaying "Page X of Y"
-              'page_number' => 1,
-              'num_pages' => num_pages,
-              'per_page' => per_page,
-
-              # The range of article numbers on this page
-              # (1-based, for showing "Items X to Y of Z")
-              'page_start' => 1,
-              'page_end' => [per_page, articles.length].min,
-
-              # These contain the next and previous page.
-              # They are set to nil if there are no more pages.
-              # The nils are overwritten when the later pages are generated, below.
-              'next_page' => nil,
-              'prev_page' => nil,
-
-              # The list of articles for this page.
-              'page_articles' => articles[0..per_page-1],
-
-              # Include the articles so that non-proxied pages can use "articles" instead
-              # of "blog.articles" for consistency with the calendar and tag templates.
-              'articles' => articles,
-              'blog_controller' => @blog_controller
-            }
-
-            prev_page_res = res
-
-            # Create additional resources for the 2nd and subsequent pages.
-            (2..num_pages).each do |num|
-              p = ::Middleman::Sitemap::Resource.new(
-                @app.sitemap,
-                page_sub(res, num, page_link),
-                res.source_file
-              )
-
-              # Copy the metadata from the base page.
-              p.add_metadata md
-
-              # Copy the proxy state from the base page.
-              p.proxy_to(res.proxied_to) if res.proxy?
-
-              page_start = (num-1)*per_page
-              page_end   = (num*per_page)-1
-
-              # Add pagination metadata, meanings as above.
-              p.add_metadata :locals => {
-                'paginate' => true,
-                'page_number' => num,
-                'num_pages' => num_pages,
-                'per_page' => per_page,
-                'page_start' => page_start+1,
-                'page_end' => [page_end+1, articles.length].min,
-                'next_page' => nil,
-                'prev_page' => prev_page_res,
-                'page_articles' => articles[page_start..page_end],
-                'articles' => articles,
-                'blog_controller' => @blog_controller
-              }
-
-              # Add a reference in the previous page to this page
-              prev_page_res.add_metadata :locals => {
-                'next_page' => p
-              }
-
-              prev_page_res = p
-
-              new_resources << p
-            end
-          end
-        end
-
-        resources + new_resources
-      end
     end
   end
 end

data/lib/middleman-blog/tag_pages.rb

@@ -1,67 +1,49 @@
+require 'middleman-blog/uri_templates'
+
 module Middleman
   module Blog
-
-    # A sitemap plugin that adds tag pages to the sitemap
-    # based on the tags of blog articles.
+    # A sitemap resource manipulator that adds a tag page to the sitemap
+    # for each tag in the associated blog
     class TagPages
-      class << self
-        # Get a path to the given tag, based on the :taglink setting.
-        # @param [Hash] blog_options
-        # @param [String] tag
-        # @return [String]
-        def link(blog_options, tag)
-          ::Middleman::Util.normalize_path(blog_options.taglink.sub(':tag', tag.parameterize))
-        end
-      end
+      include UriTemplates
 
-      def initialize(app, controller=nil)
-        @app = app
-        @blog_controller = controller
+      def initialize(app, blog_controller)
+        @sitemap = app.sitemap
+        @blog_controller = blog_controller
+        @tag_link_template = uri_template blog_controller.options.taglink
+        @tag_template = blog_controller.options.tag_template
+        @blog_data = blog_controller.data
       end
 
-      def blog_data
-        if @blog_controller
-          @blog_controller.data
-        else
-          @app.blog
-        end
+      # Get a path to the given tag, based on the :taglink setting.
+      # @param [String] tag
+      # @return [String]
+      def link(tag)
+        apply_uri_template @tag_link_template, tag: safe_parameterize(tag)
       end
 
-      def blog_options
-        if @blog_controller
-          @blog_controller.options
-        else
-          @app.blog.options
-        end
-      end
-      
       # Update the main sitemap resource list
       # @return [void]
       def manipulate_resource_list(resources)
-        resources + self.blog_data.tags.map do |tag, articles|
-          path = TagPages.link(self.blog_options, tag)
-          
-          p = ::Middleman::Sitemap::Resource.new(
-            @app.sitemap,
-            path
-          )
-          p.proxy_to(self.blog_options.tag_template)
+        resources + @blog_data.tags.map do |tag, articles|
+          tag_page_resource(tag, articles)
+        end
+      end
+
+      private
+
+      def tag_page_resource(tag, articles)
+        Sitemap::Resource.new(@sitemap, link(tag)).tap do |p|
+          p.proxy_to(@tag_template)
 
           # Add metadata in local variables so it's accessible to
           # later extensions
-          p.add_metadata :locals => {
+          p.add_metadata locals: {
             'page_type' => 'tag',
             'tagname' => tag,
             'articles' => articles,
             'blog_controller' => @blog_controller
           }
-          # Add metadata in instance variables for backwards compatibility
-          p.add_metadata do
-            @tag = tag
-            @articles = articles
-          end
-
-          p
         end
       end
     end