j1-paginator 2020.0.1

data/lib/j1-paginator/generator/paginator.rb

@@ -0,0 +1,104 @@
+module Jekyll
+  module J1Paginator::Generator
+
+    # Handles the preparation of all the posts based on the current page index
+    class Paginator
+      attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
+        :previous_page, :previous_page_path, :next_page, :next_page_path, :page_path, :page_trail,
+        :first_page, :first_page_path, :last_page, :last_page_path
+
+      def page_trail=(page_array)
+        @page_trail = page_array
+      end
+      
+      # Initialize a new Paginator.
+      def initialize(config_per_page, first_index_page_url, paginated_page_url, posts, cur_page_nr, num_pages, default_indexpage, default_ext)
+        @page = cur_page_nr
+        @per_page = config_per_page.to_i
+        @total_pages = num_pages
+
+        if @page > @total_pages
+          raise RuntimeError, "page number can't be greater than total pages: #{@page} > #{@total_pages}"
+        end
+
+        init = (@page - 1) * @per_page
+        offset = (init + @per_page - 1) >= posts.size ? posts.size : (init + @per_page - 1)
+
+        # Ensure that the current page has correct extensions if needed
+        this_page_url = Utils.ensure_full_path(@page == 1 ? first_index_page_url : paginated_page_url,
+                                               !default_indexpage || default_indexpage.length == 0 ? 'index' : default_indexpage,
+                                               !default_ext || default_ext.length == 0 ? '.html' : default_ext)
+        
+        # To support customizable pagination pages we attempt to explicitly
+        # append the page name to the url incase the user is using extensionless
+        # permalinks.
+        if default_indexpage && default_indexpage.length > 0
+          # Adjust first page url
+          first_index_page_url = Utils.ensure_full_path(first_index_page_url, default_indexpage, default_ext)
+          # Adjust the paginated pages as well
+          paginated_page_url = Utils.ensure_full_path(paginated_page_url, default_indexpage, default_ext)
+        end        
+
+        @total_posts = posts.size
+        @posts = posts[init..offset]
+        @page_path = Utils.format_page_number(this_page_url, cur_page_nr, @total_pages)
+
+        @previous_page = @page != 1 ? @page - 1 : nil
+        @previous_page_path = @page == 1 ? nil : 
+                              @page == 2 ? Utils.format_page_number(first_index_page_url, 1, @total_pages) : 
+                              Utils.format_page_number(paginated_page_url, @previous_page, @total_pages)
+        @next_page = @page != @total_pages ? @page + 1 : nil
+        @next_page_path = @page != @total_pages ? Utils.format_page_number(paginated_page_url, @next_page, @total_pages) : nil
+
+        @first_page = 1
+        @first_page_path = Utils.format_page_number(first_index_page_url, 1, @total_pages)
+        @last_page = @total_pages
+        @last_page_path = Utils.format_page_number(paginated_page_url, @total_pages, @total_pages)
+      end
+
+      # Convert this Paginator's data to a Hash suitable for use by Liquid.
+      # Returns the Hash representation of this Paginator.
+      def to_liquid
+        {
+          'per_page' => per_page,
+          'posts' => posts,
+          'total_posts' => total_posts,
+          'total_pages' => total_pages,
+          'page' => page,
+          'page_path' => page_path,
+          'previous_page' => previous_page,
+          'previous_page_path' => previous_page_path,
+          'next_page' => next_page,
+          'next_page_path' => next_page_path,
+          'first_page' => first_page,
+          'first_page_path' => first_page_path,
+          'last_page' => last_page,
+          'last_page_path' => last_page_path,
+          'page_trail' => page_trail
+        }
+      end
+      
+    end # class Paginator
+
+    # Small utility class that handles individual pagination trails 
+    # and makes them easier to work with in Liquid
+    class PageTrail
+      attr_reader :num, :path, :title
+
+      def initialize( num, path, title )
+        @num = num
+        @path = path
+        @title = title
+      end #func initialize
+
+      def to_liquid
+        {
+          'num' => num,
+          'path' => path,
+          'title' => title
+        }
+      end
+    end #class PageTrail
+
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1-paginator/generator/utils.rb

@@ -0,0 +1,176 @@
+module Jekyll 
+  module J1Paginator::Generator
+
+    #
+    # Static utility functions that are used in the code and 
+    # don't belong in once place in particular
+    #
+    class Utils
+
+      # Static: Calculate the number of pages.
+      #         all_posts - The Array of all Posts.
+      #         per_page  - The Integer of entries per page.
+      #
+      #         Returns the Integer number of pages.
+      def self.calculate_number_of_pages(all_posts, per_page)
+        (all_posts.size.to_f / per_page.to_i).ceil
+      end
+
+      # Static: returns a fully formatted string with the current (:num)
+      #         page number and maximum (:max) page count replaced if
+      #         configured
+      def self.format_page_number(toFormat, cur_page_nr, total_page_count=nil)
+        s = toFormat.sub(':num', cur_page_nr.to_s)
+        if !total_page_count.nil?
+          s = s.sub(':max', total_page_count.to_s)
+        end
+        return s
+      end #function format_page_number
+
+      # Static: returns a fully formatted string with the :title variable
+      #         and the current (:num) page number and maximum (:max) page
+      #         count replaced
+      def self.format_page_title(toFormat, title, cur_page_nr=nil, total_page_count=nil)
+        return format_page_number(toFormat.sub(':title', title.to_s), cur_page_nr, total_page_count)
+      end #function format_page_title
+
+      # Static: Return a String version of the input which has a leading dot.
+      #         If the input already has a dot in position zero, it will be
+      #         returned unchanged.
+      #
+      # path - a String path
+      #
+      # Returns the path with a leading slash
+      def self.ensure_leading_dot(path)
+        path[0..0] == "." ? path : ".#{path}"
+      end
+      
+      # Static: Return a String (path - a String path) version of the input
+      #         which has a leading slash. If the input already has a forward
+      #         slash in position zero, it will be returned unchanged.
+      #         Returns the path with a leading slash
+      def self.ensure_leading_slash(path)
+        path[0..0] == "/" ? path : "/#{path}"
+      end
+
+      # Static: Return a String version of the input without a leading slash.
+      #         path - a String path
+      #         Returns the input without the leading slash
+      def self.remove_leading_slash(path)
+        path[0..0] == "/" ? path[1..-1] : path
+      end
+      
+      # Static: Return a String version of the input which has a trailing slash.
+      #         If the input already has a forward slash at the end, it will be
+      #         returned unchanged.
+      #
+      #         path - a String path
+      #         Returns the path with a trailing slash
+      def self.ensure_trailing_slash(path)
+        path[-1] == "/" ? path : "#{path}/"
+      end
+
+      # Sorting routine used for ordering posts by custom fields.
+      # Handles Strings separately as we want a case-insenstive sorting
+      def self.sort_values(a, b)
+        if a.nil? && !b.nil?
+          return -1
+        elsif !a.nil? && b.nil?
+          return 1
+        end
+
+        if a.is_a?(String)
+          return a.downcase <=> b.downcase
+        end
+
+        if a.respond_to?('to_datetime') && b.respond_to?('to_datetime')
+          return a.to_datetime <=> b.to_datetime
+        end
+
+        # By default use the built in sorting for the data type
+        return a <=> b
+      end
+
+      # Retrieves the given sort field from the given post
+      # the sort_field variable can be a hierarchical value of the form
+      # "parent_field:child_field" repeated as many times as needed
+      # only the leaf child_field will be retrieved  
+      def self.sort_get_post_data(post_data, sort_field)
+        
+        # Begin by splitting up the sort_field by (;,:.)
+        sort_split = sort_field.split(":")
+        sort_value = post_data
+
+        sort_split.each do |r_key|
+          # Remove any erroneous whitespace and convert to lower case
+          key = r_key.downcase.strip
+          if !sort_value.has_key?(key)
+            return nil
+          end
+          # Work my way through the hash
+          sort_value = sort_value[key]
+        end
+
+        # If the sort value is a hash then return nil else return the value
+        if( sort_value.is_a?(Hash) )
+          return nil
+        else
+          return sort_value
+        end
+      end
+
+      # Ensures that the passed in url has a index and extension applied
+      def self.ensure_full_path(url, default_index, default_ext)
+        if( url.end_with?('/'))
+          return url + default_index + default_ext
+        elsif !url.include?('.')
+          return url + default_index
+        end
+        # Default
+        return url
+      end
+
+      # Constructs the plural for a key
+      def self.plural(config_key)
+        (config_key =~ /s$/) ? config_key :
+          (config_key.dup.sub!(/y$/, 'ies') || "#{config_key}s")
+      end
+
+      # Converts a string or array to a downcased, stripped array
+      def self.config_array(config, key, keepcase = nil)
+        [ config[key] ].flatten.compact.uniq.map { |c|
+          c.split(/[,;]\s*/).map { |v|
+            keepcase ? v.to_s.strip : v.to_s.downcase.strip
+          }
+        }.flatten.uniq
+      end
+
+      # Merges singular and plural config values into an array
+      def self.config_values(config, key, keepcase = nil)
+        singular = config_array(config, key, keepcase)
+        plural = config_array(config, plural(key), keepcase)
+        [ singular, plural ].flatten.uniq
+      end
+
+      def self.validate_url(template)
+        url  = template.url
+        ext  = template.output_ext
+        path = Jekyll::URL.unescape_path(url)
+        path = File.join(path, "index") if url.end_with?("/")
+        path << ext unless path.end_with?(ext)
+
+        dirname = File.dirname(path)
+        valid_values = [
+          File.join(dirname, "/"),
+          File.join(dirname, "index#{ext}")
+        ]
+
+        return url if valid_values.include?(url)
+        Jekyll.logger.error "Pagination Error:",
+          "Detected invalid url #{url.inspect} for #{template.relative_path.inspect}"
+        Jekyll.logger.abort_with "", "Expected #{valid_values.map(&:inspect).join(' or ')}"
+      end
+    end
+
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1-paginator/version.rb

@@ -0,0 +1,10 @@
+module Jekyll
+  module J1Paginator
+    VERSION = "2020.0.1"
+    # When modifying remember to issue a new tag command in git before committing, then push the new tag
+    #   git tag -a v2.1.0 -m "Gem v2.1.0"
+    #   git push origin --tags
+    # Yanking a published Gem
+    #   gem yank j1-paginator -v VERSION
+  end # module J1Paginator
+end # module Jekyll

data/spec/generator/defaults_spec.rb

@@ -0,0 +1,34 @@
+require_relative '../spec_helper.rb'
+
+module Jekyll::J1Paginator::Generator
+  describe "checking default config" do
+
+    it "should always contain the following keys" do
+      DEFAULT.must_include 'enabled'
+      DEFAULT.must_include 'collection'
+      DEFAULT.must_include 'per_page'
+      DEFAULT.must_include 'permalink'
+      DEFAULT.must_include 'title'
+      DEFAULT.must_include 'page_num'
+      DEFAULT.must_include 'sort_reverse'
+      DEFAULT.must_include 'sort_field'
+      DEFAULT.must_include 'limit'
+      DEFAULT.must_include 'debug'
+      DEFAULT.size.must_be :>=, 10
+    end
+
+    it "should always contain the following key defaults" do
+      DEFAULT['enabled'].must_equal false
+      DEFAULT['collection'].must_equal 'posts'
+      DEFAULT['per_page'].must_equal 10
+      DEFAULT['permalink'].must_equal '/page:num/'
+      DEFAULT['title'].must_equal ':title - page :num'
+      DEFAULT['page_num'].must_equal 1
+      DEFAULT['sort_reverse'].must_equal false
+      DEFAULT['sort_field'].must_equal 'date'
+      DEFAULT['limit'].must_equal 0
+      DEFAULT['debug'].must_equal false
+    end
+
+  end
+end

data/spec/generator/paginationPage_spec.rb

@@ -0,0 +1,12 @@
+require_relative '../spec_helper.rb'
+
+module Jekyll::J1Paginator::Generator
+  describe "tesing pagination page implementation" do
+
+    it "sould always read the template file into itself" do
+      # DUE TO THE JEKYLL:PAGE CLASS ACCESSING FILE IO DIRECTLY 
+      # I AM UNABLE TO MOCK OUT THE FILE OPERATIONS TO CREATE UNIT TESTS FOR THIS CLASS :/
+    end
+
+  end
+end

data/spec/generator/paginator_spec.rb

@@ -0,0 +1,197 @@
+require_relative '../spec_helper.rb'
+
+module Jekyll::J1Paginator::Generator
+  describe Paginator do
+
+    it "must include the necessary paginator attributes" do
+
+      #  config_per_page, first_index_page_url, paginated_page_url, posts, cur_page_nr, num_pages
+      pager = Paginator.new(10, "index.html", "/page:num/", [], 1, 10, 'index', '.html')
+
+      # None of these accessors should throw errors, just run through them to test
+      val = pager.page
+      val = pager.per_page
+      val = pager.posts
+      val = pager.total_posts
+      val = pager.total_pages
+      val = pager.previous_page
+      val = pager.previous_page_path
+      val = pager.next_page
+      val = pager.next_page_path
+      
+    end
+
+    it "must throw an error if the current page number is greater than the total pages" do
+      err = -> { pager = Paginator.new(10, "index.html", "/page:num/", [], 10, 8, 'index', '.html') }.must_raise RuntimeError
+
+      # No error should be raised below
+      pager = Paginator.new(10, "index.html", "/page:num/", [], 8, 10, 'index', '.html')
+    end
+
+    it "must trim the list of posts correctly based on the cur_page_nr and per_page" do
+      # Create a dummy list of posts that is easy to track
+      posts = [
+        '1','2','3','4','5',
+        '6','7','8','9','10',
+        '11','12','13','14','15',
+        '16','17','18','19','20',
+        '21','22','23','24','25',
+        '26','27','28','29','30',
+        '31','32','33','34','35'
+      ]
+
+      # Initialize a pager with
+      #   5 posts per page
+      #   at page 2 out of 5 pages
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 2, 5, '', '')
+
+      pager.page.must_equal 2
+      pager.per_page.must_equal 5
+      pager.total_pages.must_equal 5
+
+      pager.total_posts.must_equal 35
+
+      pager.posts.size.must_equal 5
+      pager.posts[0].must_equal '6'
+      pager.posts[4].must_equal '10'
+
+      pager.previous_page.must_equal 1
+      pager.previous_page_path.must_equal 'index.html'
+      pager.next_page.must_equal 3
+      pager.next_page_path.must_equal '/page3/'
+    end
+
+    it "must not create a previous page if we're at first page" do
+      # Create a dummy list of posts that is easy to track
+      posts = [
+        '1','2','3','4','5',
+        '6','7','8','9','10',
+        '11','12','13','14','15',
+        '16','17','18','19','20',
+        '21','22','23','24','25',
+        '26','27','28','29','30',
+        '31','32','33','34','35'
+      ]
+
+      # Initialize a pager with
+      #   5 posts per page
+      #   at page 1 out of 5 pages
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 1, 5, '', '')
+
+      pager.page.must_equal 1
+      pager.per_page.must_equal 5
+      pager.total_pages.must_equal 5
+
+      pager.total_posts.must_equal 35
+
+      pager.posts.size.must_equal 5
+      pager.posts[0].must_equal '1'
+      pager.posts[4].must_equal '5'
+
+      pager.previous_page.must_be_nil
+      pager.previous_page_path.must_be_nil
+      pager.next_page.must_equal 2
+      pager.next_page_path.must_equal '/page2/'
+    end
+
+    it "must not create a next page if we're at the final page" do
+      # Create a dummy list of posts that is easy to track
+      posts = [
+        '1','2','3','4','5',
+        '6','7','8','9','10',
+        '11','12','13','14','15',
+        '16','17','18','19','20',
+        '21','22','23','24','25',
+        '26','27','28','29','30',
+        '31','32','33','34','35'
+      ]
+
+      # Initialize a pager with
+      #   5 posts per page
+      #   at page 5 out of 5 pages
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 5, 5, '', '')
+
+      pager.page.must_equal 5
+      pager.per_page.must_equal 5
+      pager.total_pages.must_equal 5
+
+      pager.total_posts.must_equal 35
+
+      pager.posts.size.must_equal 5
+      pager.posts[0].must_equal '21'
+      pager.posts[4].must_equal '25'
+
+      pager.previous_page.must_equal 4
+      pager.previous_page_path.must_equal '/page4/'
+      pager.next_page.must_be_nil
+      pager.next_page_path.must_be_nil
+    end
+
+    it "must create the explicit index page and index extension when specified" do
+      # Create a dummy list of posts that is easy to track
+      posts = [
+        '1','2','3','4','5',
+        '6','7','8','9','10',
+        '11','12','13','14','15',
+        '16','17','18','19','20',
+        '21','22','23','24','25',
+        '26','27','28','29','30',
+        '31','32','33','34','35'
+      ]
+
+      # Initialize a pager with
+      #   5 posts per page
+      #   at page 2 out of 5 pages
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 2, 5, 'index', '.html')
+
+      pager.page.must_equal 2
+      pager.per_page.must_equal 5
+      pager.total_pages.must_equal 5
+
+      pager.total_posts.must_equal 35
+
+      pager.posts.size.must_equal 5
+      pager.posts[0].must_equal '6'
+      pager.posts[4].must_equal '10'
+
+      pager.previous_page.must_equal 1
+      pager.previous_page_path.must_equal 'index.html'
+      pager.next_page.must_equal 3
+      pager.next_page_path.must_equal '/page3/index.html'
+    end
+
+    it "must create the explicit index page and index extension when specified" do
+      # Create a dummy list of posts that is easy to track
+      posts = [
+        '1','2','3','4','5',
+        '6','7','8','9','10',
+        '11','12','13','14','15',
+        '16','17','18','19','20',
+        '21','22','23','24','25',
+        '26','27','28','29','30',
+        '31','32','33','34','35'
+      ]
+
+      # Initialize a pager with
+      #   5 posts per page
+      #   at page 2 out of 5 pages
+      pager = Paginator.new(5, "/", "/", posts, 2, 5, 'feed:num', '.json')
+
+      pager.page.must_equal 2
+      pager.per_page.must_equal 5
+      pager.total_pages.must_equal 5
+
+      pager.total_posts.must_equal 35
+
+      pager.posts.size.must_equal 5
+      pager.posts[0].must_equal '6'
+      pager.posts[4].must_equal '10'
+
+      pager.previous_page.must_equal 1
+      pager.previous_page_path.must_equal '/feed1.json'
+      pager.next_page.must_equal 3
+      pager.next_page_path.must_equal '/feed3.json'
+    end
+
+  end
+end