j1_paginator 2019.1.0

data/lib/j1_paginator/autopages/utils.rb

@@ -0,0 +1,76 @@
+module Jekyll
+  module J1Paginator::AutoPages
+
+    class Utils
+
+      # Static: returns a fully formatted string with the tag macro (:tag) replaced
+      #
+      def self.format_tag_macro(toFormat, tag, slugify_config=nil)
+        slugify_mode = slugify_config.has_key?('mode') ? slugify_config['mode'] : nil
+        slugify_cased = slugify_config.has_key?('cased') ? slugify_config['cased'] : false
+        return toFormat.sub(':tag', Jekyll::Utils.slugify(tag.to_s, mode:slugify_mode, cased:slugify_cased))
+      end #function format_tag_macro
+
+      # Static: returns a fully formatted string with the category macro (:cat) replaced
+      #
+      def self.format_cat_macro(toFormat, category, slugify_config=nil)
+        slugify_mode = slugify_config.has_key?('mode') ? slugify_config['mode'] : nil
+        slugify_cased = slugify_config.has_key?('cased') ? slugify_config['cased'] : false
+        return toFormat.sub(':cat', Jekyll::Utils.slugify(category.to_s, mode:slugify_mode, cased:slugify_cased))
+      end #function format_cat_macro
+
+      # Static: returns a fully formatted string with the collection macro (:coll) replaced
+      #
+      def self.format_coll_macro(toFormat, collection, slugify_config=nil)
+        slugify_mode = slugify_config.has_key?('mode') ? slugify_config['mode'] : nil
+        slugify_cased = slugify_config.has_key?('cased') ? slugify_config['cased'] : false
+        return toFormat.sub(':coll', Jekyll::Utils.slugify(collection.to_s, mode:slugify_mode, cased:slugify_cased))
+      end #function format_coll_macro
+
+      # Static: returns all documents from all collections defined in the hash of collections passed in
+      # excludes all pagination pages though
+      def self.collect_all_docs(site_collections)
+        coll = []
+        site_collections.each do |coll_name, coll_data|
+          if !coll_data.nil?
+            coll += coll_data.docs.select { |doc| !doc.data.has_key?('pagination') }.each{ |doc| doc.data['__coll'] = coll_name } # Exclude all pagination pages and then for every page store it's collection name
+          end
+        end
+        return coll
+      end
+
+      def self.ap_index_posts_by(all_posts, index_key)
+        return nil if all_posts.nil?
+        return all_posts if index_key.nil?
+        index = {}
+        all_posts.each do |post|
+          next if post.data.nil?
+          next if !post.data.has_key?(index_key)
+          next if post.data[index_key].nil?
+          next if post.data[index_key].size <= 0
+          next if post.data[index_key].to_s.strip.length == 0
+
+          # Only tags and categories come as premade arrays, locale does not, so convert any data
+          # elements that are strings into arrays
+          post_data = post.data[index_key]
+          if post_data.is_a?(String)
+            post_data = post_data.split(/;|,|\s/)
+          end
+
+          post_data.each do |key|
+            key = key.to_s.strip
+            processed_key = key.downcase #Clean whitespace and junk
+            if !index.has_key?(processed_key)
+              # Need to store the original key value here so that I can present it to the users as a page variable they can use (unmodified, e.g. tags not being 'sci-fi' but "Sci-Fi")
+              # Also, only interested in storing all the keys not the pages in this case
+              index[processed_key] = [processed_key, key]
+            end
+          end
+        end
+        return index
+      end # function index_posts_by
+
+    end # class Utils
+
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1_paginator/generator/compatibilityUtils.rb

@@ -0,0 +1,121 @@
+module Jekyll 
+  module J1Paginator::Generator
+
+    class CompatibilityPaginationPage < Page
+      def initialize(site, base, dir, template_path)
+        @site = site
+        @base = base
+        @dir = dir
+        @template = template_path
+        @name = 'index.html'
+
+        templ_dir = File.dirname(template_path)
+        templ_file = File.basename(template_path)
+
+        # Path is only used by the convertible module and accessed below when calling read_yaml
+        # in our case we have the path point to the original template instead of our faux new pagination page
+        @path = if site.in_theme_dir(base) == base # we're in a theme
+                  site.in_theme_dir(base, templ_dir, templ_file)
+                else
+                  site.in_source_dir(base, templ_dir, templ_file)
+                end
+        
+        self.process(@name)
+        self.read_yaml(templ_dir, templ_file)
+
+        data.default_proc = proc do |_, key|
+          site.frontmatter_defaults.find(File.join(templ_dir, templ_file), type, key)
+        end
+
+      end
+    end # class CompatibilityPaginationPage
+
+    #
+    # Static utility functions that provide backwards compatibility with the old 
+    # jekyll-paginate gem that this new version superseeds (this code is here to ensure)
+    # that sites still running the old gem work without problems
+    # (REMOVE AFTER 2018-01-01)
+    #
+    # THIS CLASS IS ADAPTED FROM THE ORIGINAL IMPLEMENTATION AND WILL BE REMOVED, THERE ARE DELIBERATELY NO TESTS FOR THIS CLASS
+    #
+    class CompatibilityUtils
+
+      # Public: Find the Jekyll::Page which will act as the pager template
+      #
+      # Returns the Jekyll::Page which will act as the pager template
+      def self.template_page(site_pages, config_source, config_paginate_path)
+        site_pages.select do |page|
+          CompatibilityUtils.pagination_candidate?(config_source, config_paginate_path, page)
+        end.sort do |one, two|
+          two.path.size <=> one.path.size
+        end.first
+      end
+
+      # Static: Determine if a page is a possible candidate to be a template page.
+      #         Page's name must be `index.html` and exist in any of the directories
+      #         between the site source and `paginate_path`.
+      def self.pagination_candidate?(config_source, config_paginate_path, page)
+        page_dir = File.dirname(File.expand_path(Utils.remove_leading_slash(page.path), config_source))
+        paginate_path = Utils.remove_leading_slash(config_paginate_path)
+        paginate_path = File.expand_path(paginate_path, config_source)
+        page.name == 'index.html' && CompatibilityUtils.in_hierarchy(config_source, page_dir, File.dirname(paginate_path))
+      end
+
+      # Determine if the subdirectories of the two paths are the same relative to source
+      #
+      # source        - the site source
+      # page_dir      - the directory of the Jekyll::Page
+      # paginate_path - the absolute paginate path (from root of FS)
+      #
+      # Returns whether the subdirectories are the same relative to source
+      def self.in_hierarchy(source, page_dir, paginate_path)
+        return false if paginate_path == File.dirname(paginate_path)
+        return false if paginate_path == Pathname.new(source).parent
+        page_dir == paginate_path ||
+          CompatibilityUtils.in_hierarchy(source, page_dir, File.dirname(paginate_path))
+      end
+
+      # Paginates the blog's posts. Renders the index.html file into paginated
+      # directories, e.g.: page2/index.html, page3/index.html, etc and adds more
+      # site-wide data.
+      #
+      def self.paginate(legacy_config, all_posts, page, page_add_lambda )
+        pages = Utils.calculate_number_of_pages(all_posts, legacy_config['per_page'].to_i)
+        (1..pages).each do |num_page|
+          pager = Paginator.new( legacy_config['per_page'], page.url, legacy_config['permalink'], all_posts, num_page, pages, '', '' )
+          if num_page > 1
+            template_full_path = File.join(page.site.source, page.path)
+            template_dir = File.dirname(page.path)
+            newpage = CompatibilityPaginationPage.new(page.site, page.site.source, template_dir, template_full_path)
+            newpage.pager = pager
+            newpage.dir = CompatibilityUtils.paginate_path(page.url, num_page, legacy_config['permalink'])
+            newpage.data['autogen'] = "j1_paginator" # Signals that this page is automatically generated by the pagination logic
+            page_add_lambda.call(newpage)
+          else
+            page.pager = pager
+          end
+        end
+      end
+
+      # Static: Return the pagination path of the page
+      #
+      # site     - the Jekyll::Site object
+      # cur_page_nr - the pagination page number
+      # config - the current configuration in use
+      #
+      # Returns the pagination path as a string
+      def self.paginate_path(template_url, cur_page_nr, permalink_format)
+        return nil if cur_page_nr.nil?
+        return template_url if cur_page_nr <= 1
+        if permalink_format.include?(":num")
+          permalink_format = Utils.format_page_number(permalink_format, cur_page_nr)
+        else
+          raise ArgumentError.new("Invalid pagination path: '#{permalink_format}'. It must include ':num'.")
+        end
+
+        Utils.ensure_leading_slash(permalink_format)
+      end #function paginate_path
+
+    end # class CompatibilityUtils
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1_paginator/generator/defaults.rb

@@ -0,0 +1,27 @@
+module Jekyll
+  module J1Paginator::Generator
+
+    # The default configuration for the Paginator
+    DEFAULT = {
+      'enabled'      => false,
+      'collection'   => 'posts',
+      'offset'       => 0, # Supports skipping x number of posts from the beginning of the post list
+      'per_page'     => 10,
+      'permalink'    => '/page:num/', # Supports :num as customizable elements
+      'title'        => ':title - page :num', # Supports :num as customizable elements
+      'page_num'     => 1,
+      'sort_reverse' => false,
+      'sort_field'   => 'date',
+      'limit'        => 0, # Limit how many content objects to paginate (default: 0, means all)
+      'trail'        => { 
+          'before' => 0, # Limits how many links to show before the current page in the pagination trail (0, means off, default: 0)
+          'after' => 0,  # Limits how many links to show after the current page in the pagination trail (0 means off, default: 0)
+      },
+      'indexpage'    => 'index', # The default name of the index pages
+      'extension'    => 'html', # The default extension for the output pages (ignored if indexpage is nil)
+      'debug'        => false, # Turns on debug output for the gem
+      'legacy'       => false # Internal value, do not use (will be removed after 2018-01-01)
+    }
+
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1_paginator/generator/paginationGenerator.rb

@@ -0,0 +1,146 @@
+module Jekyll
+  module J1Paginator::Generator
+  
+    #
+    # The main entry point into the generator, called by Jekyll
+    # this function extracts all the necessary information from the jekyll end and passes it into the pagination 
+    # logic. Additionally it also contains all site specific actions that the pagination logic needs access to
+    # (such as how to create new pages)
+    # 
+    class PaginationGenerator < Generator
+      # This generator is safe from arbitrary code execution.
+      safe true
+
+      # This generator should be passive with regard to its execution
+      priority :lowest
+      
+      # Generate paginated pages if necessary (Default entry point)
+      # site - The Site.
+      #
+      # Returns nothing.
+      def generate(site)
+      #begin
+        # Generate the AutoPages first
+        J1Paginator::AutoPages.create_autopages(site)
+
+        # Retrieve and merge the pagination configuration from the site yml file
+        default_config = Jekyll::Utils.deep_merge_hashes(DEFAULT, site.config['pagination'] || {})
+
+        # Compatibility Note: (REMOVE AFTER 2018-01-01)
+        # If the legacy paginate logic is configured then read those values and merge with config
+        if !site.config['paginate'].nil?
+          Jekyll.logger.info "Pagination:","Legacy paginate configuration settings detected and will be used."
+          # You cannot run both the new code and the old code side by side
+          if !site.config['pagination'].nil?
+            err_msg = "The new j1_paginator and the old jekyll-paginate logic cannot both be configured in the site config at the same time. Please disable the old 'paginate:' config settings by either omitting the values or setting them to 'paginate:off'."
+            Jekyll.logger.error err_msg 
+            raise ArgumentError.new(err_msg)
+          end
+
+          default_config['per_page'] = site.config['paginate'].to_i
+          default_config['legacy_source'] = site.config['source']
+          if !site.config['paginate_path'].nil?
+            default_config['permalink'] = site.config['paginate_path'].to_s
+          end
+          # In case of legacy, enable pagination by default
+          default_config['enabled'] = true
+          default_config['legacy'] = true
+        end # Compatibility END (REMOVE AFTER 2018-01-01)
+
+        # If disabled then simply quit
+        if !default_config['enabled']
+          Jekyll.logger.info "Pagination:","Disabled in site.config."
+          return
+        end
+
+        # Handle deprecation of settings and features
+        if( !default_config['title_suffix' ].nil? )
+          Jekyll::Deprecator.deprecation_message "Pagination: The 'title_suffix' configuration has been deprecated. Please use 'title'. See https://github.com/sverrirs/j1_paginator/blob/master/README-GENERATOR.md#site-configuration"
+        end
+
+        Jekyll.logger.debug "Pagination:","Starting"
+
+        ################ 0 #################### 
+        # Get all pages in the site (this will be used to find the pagination templates)
+        all_pages = site.pages
+
+        # Get the default title of the site (used as backup when there is no title available for pagination)
+        site_title = site.config['title']
+
+        ################ 1 #################### 
+        # Specify the callback function that returns the correct docs/posts based on the collection name
+        # "posts" are just another collection in Jekyll but a specialized version that require timestamps
+        # This collection is the default and if the user doesn't specify a collection in their front-matter then that is the one we load
+        # If the collection is not found then empty array is returned
+        collection_by_name_lambda = lambda do |collection_name|
+          coll = []
+          if collection_name == "all"
+            # the 'all' collection_name is a special case and includes all collections in the site (except posts!!)
+            # this is useful when you want to list items across multiple collections
+            site.collections.each do |coll_name, coll_data|
+              if( !coll_data.nil? && coll_name != 'posts')
+                coll += coll_data.docs.select { |doc| !doc.data.has_key?('pagination') } # Exclude all pagination pages
+              end
+            end
+          else
+            # Just the one collection requested
+            if !site.collections.has_key?(collection_name)
+              return []
+            end
+
+            coll = site.collections[collection_name].docs.select { |doc| !doc.data.has_key?('pagination') } # Exclude all pagination pages
+          end
+          return coll
+        end
+
+        ################ 2 ####################
+        # Create the proc that constructs the real-life site page
+        # This is necessary to decouple the code from the Jekyll site object
+        page_add_lambda = lambda do | newpage |
+          site.pages << newpage # Add the page to the site so that it is generated correctly
+          return newpage # Return the site to the calling code
+        end
+
+        ################ 2.5 ####################
+        # lambda that removes a page from the site pages list
+        page_remove_lambda = lambda do | page_to_remove |
+          site.pages.delete_if {|page| page == page_to_remove } 
+        end
+
+        ################ 3 ####################
+        # Create a proc that will delegate logging
+        # Decoupling Jekyll specific logging
+        logging_lambda = lambda do | message, type="info" |
+          if type == 'debug'
+            Jekyll.logger.debug "Pagination:","#{message}"
+          elsif type == 'error'
+            Jekyll.logger.error "Pagination:", "#{message}"
+          elsif type == 'warn'
+            Jekyll.logger.warn "Pagination:", "#{message}"
+          else
+            Jekyll.logger.info "Pagination:", "#{message}"
+          end
+        end
+
+        ################ 4 ####################
+        # Now create and call the model with the real-life page creation proc and site data
+        model = PaginationModel.new(logging_lambda, page_add_lambda, page_remove_lambda, collection_by_name_lambda)
+        if( default_config['legacy'] ) #(REMOVE AFTER 2018-01-01)
+          Jekyll.logger.warn "Pagination:", "You are running jekyll-paginate backwards compatible pagination logic. Please ignore all earlier warnings displayed related to the old jekyll-paginate gem."
+          all_posts = site.site_payload['site']['posts'].reject { |post| post['hidden'] }
+          model.run_compatability(default_config, all_pages, site_title, all_posts) #(REMOVE AFTER 2018-01-01)
+        else
+          count = model.run(default_config, all_pages, site_title)
+          Jekyll.logger.info ""
+          Jekyll.logger.info "Pagination:", "Complete, processed #{count} pagination page(s)"
+        end
+
+      #rescue => ex
+      #  puts ex.backtrace
+      #  raise
+      #end
+      end # function generate
+    end # class PaginationGenerator
+
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1_paginator/generator/paginationIndexer.rb

@@ -0,0 +1,116 @@
+module Jekyll
+  module J1Paginator::Generator
+
+    # 
+    # Performs indexing of the posts or collection documents
+    # as well as filtering said collections when requested by the defined filters.
+    class PaginationIndexer
+      #
+      # Create a hash index for all post based on a key in the post.data table
+      #
+      def self.index_posts_by(all_posts, index_key)
+        return nil if all_posts.nil?
+        return all_posts if index_key.nil?
+        index = {}
+        all_posts.each do |post|
+          next if post.data.nil?
+          next if !post.data.has_key?(index_key)
+          next if post.data[index_key].nil?
+          next if post.data[index_key].size <= 0
+          next if post.data[index_key].to_s.strip.length == 0
+          
+          # Only tags and categories come as premade arrays, locale does not, so convert any data
+          # elements that are strings into arrays
+          post_data = post.data[index_key]
+          if post_data.is_a?(String)
+            post_data = post_data.split(/;|,|\s/)
+          end
+          
+          post_data.each do |key|
+            key = key.to_s.downcase.strip
+            # If the key is a delimetered list of values 
+            # (meaning the user didn't use an array but a string with commas)
+            key.split(/;|,/).each do |k_split|
+              k_split = k_split.to_s.downcase.strip #Clean whitespace and junk
+              if !index.has_key?(k_split)
+                index[k_split.to_s] = []
+              end
+              index[k_split.to_s] << post
+            end
+          end
+        end
+        return index
+      end # function index_posts_by
+      
+      #
+      # Creates an intersection (only returns common elements)
+      # between multiple arrays
+      #
+      def self.intersect_arrays(first, *rest)
+        return nil if first.nil?
+        return nil if rest.nil?
+        
+        intersect = first
+        rest.each do |item|
+          return [] if item.nil?
+          intersect = intersect & item
+        end
+        return intersect
+      end #function intersect_arrays
+      
+      #
+      # Filters posts based on a keyed source_posts hash of indexed posts and performs a intersection of 
+      # the two sets. Returns only posts that are common between all collections 
+      #
+      def self.read_config_value_and_filter_posts(config, config_key, posts, source_posts)
+        return nil if posts.nil?
+        return nil if source_posts.nil? # If the source is empty then simply don't do anything
+        return posts if config.nil?
+
+        plural_key = Utils.plural(config_key)
+
+        return posts if !config.has_key?(config_key) && !config.has_key?(plural_key)
+        return posts if config[config_key].nil? && config[plural_key].nil?
+        
+        # Get the filter values from the config (this is the cat/tag/locale values that should be filtered on)
+        
+        if config[config_key].is_a?(Hash) || config[plural_key].is_a?(Hash)
+          # { values: [..], matching: any|all }
+          config_hash = config[config_key].is_a?(Hash) ? config[config_key] : config[plural_key]
+          config_value = Utils.config_values(config_hash, 'value')
+          matching = config_hash['matching'] || 'all'
+        else
+          # Default array syntax
+          config_value = Utils.config_values(config, config_key)
+          matching = 'all'
+        end
+          
+        matching = matching.to_s.downcase.strip
+
+        # Filter on any/all specified categories, etc.
+
+        if matching == "all"
+          # Now for all filter values for the config key, let's remove all items from the posts that
+          # aren't common for all collections that the user wants to filter on
+          config_value.each do |key|
+            key = key.to_s.downcase.strip
+            posts = PaginationIndexer.intersect_arrays(posts, source_posts[key])
+          end
+
+        elsif matching == "any"
+          # "or" filter: Remove posts that don't have at least one required key
+          posts.delete_if { |post|
+            post_config = Utils.config_values(post.data, config_key)
+            (config_value & post_config).empty?
+          }
+
+        # else no filter
+        end
+
+        # The fully filtered final post list
+        return posts
+      end #function read_config_value_and_filter_posts
+    end #class PaginationIndexer
+
+  end #module J1Paginator
+end #module Jekyll