jekyll-pagination-task 1.0.3

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZGFlMGFkN2M3ZTk5OTc0OWYwNmY1NzIxZWZiYjQ1NTE1OWEyOTlmYg==
+  data.tar.gz: !binary |-
+    OTE5NWM0M2IyN2IzMWI5N2FlYWUxMGE4OWI3NGVhZjI2YjIzZmU2ZQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MGE2M2YzMmJiYzE1ZWQyNWEyMjFjMDM3MGUwZTdiOTcxZTQ3YmMxYTQzOTQz
+    N2NiOWU1YjJiYzUyYjllZmMzMDlhYjk3MzhjNDBlOWRjNmNmNGQ4ZWVhYmIz
+    MDUyMGQyZmE3YWQwNzI1OTljM2JkMTYyMTQ2MTE3ZTA0MmZiOTU=
+  data.tar.gz: !binary |-
+    Y2RhMDYzZDk3YTY2NGM0MzlkZThjYjExNDFiYmZkOGY1MGJlNmJjYWJhNWIw
+    YzE5NDdhYzRmODIxZmEwNzY2Yjk3OWIyMGJkMGFlNmY5MjFjOTBmYWVhZjI5
+    ZGU3MGE4NWZmYmE4ZDc5YmUwZWU1NmY5YmIzMzNiZmE3MDJiZWE=

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+*.swp

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,183 @@
+jekyll-pagination-task
+======================
+
+An advanced pagination tool for jekyll
+
+# Apology
+
+I must apologize to those who have downloaded `1.0.0` to `1.0.2` version of
+this plugin. I should have tested it in more complicated situations before
+publishing it.
+
+Also I'd like to apologize for the irresponsible pushes to [RubyGems][rubygem].
+I am new to Ruby and got overenthusiastic to have my own gem published.
+
+[rubygem]: http://rubygems.org/
+
+I really would like this plugin to be useful and hope everyone enjoys it.
+
+# Installation
+
+First you must install jekyll-pagination-task. It can be done by 
+
+~~~
+gem install jekyll-pagination-task
+~~~
+
+or download the source code and compile it locally:
+
+~~~
+git clone https://github.com/emiapwil/jekyll-pagination-task
+cd jekyll-pagination-task
+gem build jekyll-pagination-task.gemsepc
+gem install jekyll-pagination-task-{VERSION}.gem
+~~~
+
+Of course, you can just download the code and put
+`lib/jekyll-pagination-task/pagination_task.rb` to the `_plugins/` folder of
+your jekyll site.
+
+# Configuration
+
+## Site Configuration
+
+After the installation you can put the following line in the `_plugins/ext.rb`
+to make jekyll aware of its presence. If the ruby source file is put in
+`_plugins`, however, you can skip this step.
+
+~~~
+require "jekyll-pagination-task"
+~~~
+
+Then it is also required to add the following lines in `_config.yml`:
+
+~~~
+pagination_task:
+  page_per_pager: 7
+  format: /:dir/:name/:Num
+  filter_class: Jekyll::PaginationTask::DefaultPaginationFilter
+  post_only: true
+~~~
+
+The first line is crucial since it indicates that jekyll-pagination-task plugin
+will be enabled. The other three lines are all optional:
+
+- `page_per_pager`: how many pages should be include in one pager. The default
+  value is 7.
+- `format`: how the url of the generated pagers should look like. The default
+  value is `/:dir/:name/:Num`. There are currently 4 macros:
+  - `:dir`: it will be replaced by the path to the *template* page;
+  - `:name`: it will be replaced by the basename of the *template* page;
+  - `:num`: it will be replaced by the index of the generated page;
+  - `:Num`: same as `:num` expect that 1 is replaced by an empty string.
+- `filter_class`: which class to use as the filter for pages. The default value
+  is Jekyll::PaginationTask::DefaultPaginationFilter.
+- `post_only`: only paginate the posts, the default value is `true`. If set to
+  `false`, the pages will be paginated as well.
+
+## Page Configuration
+
+Unlike [jekyll-paginate][jekyll-paginate], this plugin identify *template* pages
+by checking whether the attribute `paginate` is set to `true` in a page. To make
+things more flexible, some other optional attributes can be set as well. These
+configurations are demonstrated in the following example:
+
+[jekyll-paginate]: https://github.com/jekyll/jekyll-paginate
+
+~~~
+---
+paginate: true
+page_per_pager: 8
+pagination_format: /posts/:Num
+filter_class: Jekyll::PaginationTask::DefaultPaginationFilter
+pagination_filter:
+  - ['layout', 'is', 'post']
+  - ['category', 'all', ['test', 'ruby']]
+---
+~~~
+
+- `paginate`: indicates that this page is a *template*.
+- `page_per_pager`: same as `page_per_pager` in `_config.yml`.
+- `pagination_format`: same as `format` in `_config.yml`.
+- `filter_class`: same as `filter_class` in `_config.yml`.
+- `pagination_filter`: this is used to store parameters for
+  `Jekyll::PaginationTask::DefaultPaginationFilter`, each element of it will
+  have the form of `[$ATTR, $RELATION, $PARAMETER]`. Then attribute
+  `$ATTR` of the *template* page will be checked against `$A_LIST_OF_VALUES` and
+  the pages that satisfy all these conditions will be set as the pager's *posts*
+  (this is for compatibility with jekyll-paginate). There are currently 8
+  relations supported:
+  - `all`: *true* if the attribute `$ATTR` contains all values from `$PARAMETER`
+    and otherwise *false*;
+  - `any`: *true* if the attribute `$ATTR` contains any of the values from
+    `$PARAMETER` and otherwise *false*;
+  - `only`: *true* if the attribute `$ATTR` contains values only from
+    `$PARAMETER` and otherwise *false*;
+  - `none`: *true* if the attribute `$ATTR` contains no values from
+    `$PARAMETER` and otherwise *false*;
+  - `is`: *true* if `$ATTR` equals `$PARAMETER` and *false* otherwise
+  - `is_not`: *true* if `$ATTR` doesn't equal `$PARAMETER` and *false* otherwise
+  - `in`: *true* if `$ATTR` is a member of `$PARAMETER`
+  - `not_in`: *true* if `$ATTR` is not a member of `$PARAMETER` 
+
+It is notable that the types of `$ATTR` and `$PARAMETER` are also indicated in
+these relationships and I think they can cover most cases. If the default
+filter still fails to meet the needs, you can always develop your own filter
+class and point to it by setting the `filter_class` option.
+
+# Demonstration
+
+Assuming the full name of the *template* page is `demo/post.md` which selects 45
+posts using the frontmatter above. The following files will be generated:
+`/demo/post/index.html`, `/demo/post/2/index.html`, ..., and
+`/demo/post/6/index.html`.
+
+If we have another file named `demo/post7.md` which uses the same frontmatter
+expect the `page_per_pager` line, it will use the configuration in `_config.yml`
+and 7 pages will be generated with prefix `/demo/post7/` instead of
+`/demo/post/`.
+
+If we modify the `pagination_format` in this `demo/post7.md` file to
+`/home/test/:Num`, then the pages will be generated in `/home/test/` folder
+rather than `/demo/post7`.
+
+# Work Flow
+
+Here is a quick introduction to the implementation of jekyll-pagination-task:
+
+- selects pages with `paginate` set to `true` as *templates*
+- for each *tempalte*, construct the *filter* with *site* and the *template*
+- selects pages that satisfies the filter
+- create `PTPager`, which is derived from `Jekyll::Pager` and can set up the
+  correct url for generated pagination pages. Then the generated `pager` pages
+  are appended to site.pages
+
+# Features not Supported yet
+
+- Infinite `page_per_pager`.
+- Structed options in the frontmatter.
+- Customized *Sorter* support. Currently the posts are not sorted.
+
+# BUGs
+
+I'm new to Ruby and this package is not fully tested, so there might be many
+bugs...
+
+## Known Bugs
+
+### **Unable to generate correct pages when the `url` function of the template has been called earlier**.
+ 
+The reason is that Jekyll::Page will generate the url once `url` is called and
+store it in `@url` which is not accessible thus not modifiable. One workaround
+is to hack the Jekyll package and add the `:url` to `attr_accesssor` in
+`Jekyll::Page` and then add one more line in `create_pager` just before it
+returns:
+
+~~~
+instance.url = nil # reset the url
+~~~
+
+**Update**: the hack is not necessary now since most plugins are unlikely to
+touch these template files and the problem occurred earlier is caused by a call
+to `dir` in calculating the pagination path within this plugin. It is fixed in
+a recent commit.

data/jekyll-pagination-task.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jekyll-pagination-task'
+  spec.version       = '1.0.3'
+  spec.license       = 'MIT'
+  spec.date          = '2014-12-10'
+
+  spec.summary       = 'An advanced paginator for Jekyll'
+  spec.description   = <<-DESC
+    Jekyll Pagination Task allows you to create paginated pages by
+    defining filters on attributes of all Jekyll pages.'
+  DESC
+
+  spec.author        = ['Kai Gao']
+  spec.email         = 'emiapwil@gmail.com'
+  spec.homepage      = 'http://github.com/emiapwil/jekyll-pagination-task'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'jekyll-paginate', '~> 1.1.0'
+end

data/lib/jekyll-pagination-task.rb

@@ -0,0 +1 @@
+require "jekyll-pagination-task/pagination_task"

data/lib/jekyll-pagination-task/pagination_task.rb

@@ -0,0 +1,224 @@
+module Jekyll
+  module PaginationTask
+
+    class PaginationFilter
+      def initialize(site, pager) end
+
+      def satisfy?(page)
+        false
+      end
+    end
+
+    class DefaultPaginationFilter < PaginationFilter
+      
+      def initialize(site, pager)
+        @filters = []
+        conditions = pager["pagination_filter"] || []
+        conditions.each do |condition|
+          name = condition[0]
+          relation = condition[1]
+          if !respond_to?("check_#{relation}")
+            Jekyll.logger.warn "Decteced unsupported action " + attr_action
+                                + " in pager file " + pager.url
+
+            next
+          end
+          parameters = condition[2]
+          @filters << { "name" => name, "relation" => relation, "parameters" => parameters }
+        end
+      end
+
+      def check_all(parameters, attr)
+        return false if attr.nil?
+        parameters.each { |parameter| return false if !attr.include?(parameter) }
+        true
+      end
+
+      def check_any(parameters, attr)
+        return false if attr.nil?
+        parameters.each { |parameter| return true if attr.include?(parameter) }
+        false
+      end
+
+      def check_only(parameters, attr)
+        return true if attr.nil?
+        attr.each { |attribute| return false if !parameters.include?(attribute) }
+        true
+      end
+
+      def check_none(parameters, attr)
+        return true if attr.nil?
+        parameters.each { |parameter| return false if attr.include?(parameter) }
+        true
+      end
+
+      def check_is(parameters, attr)
+        parameters === attr
+      end
+
+      def check_is_not(parameters, attr)
+        parameters != attr
+      end
+
+      def check_in(parameters, attr)
+        parameters.include?(attr)
+      end
+
+      def check_not_in(parameters, attr)
+        !parameters.include?(attr)
+      end
+
+      def satisfy?(page)
+        @filters.each do |filter|
+          relation = filter["relation"]
+          parameters = filter["parameters"]
+          attr = page[filter["name"]]
+          checker = method("check_#{relation}")
+          return false if !checker.call(parameters, attr)
+        end
+        true
+      end
+    end
+
+    class PaginationTask < Generator
+      # This generator is safe from arbitrary code execution.
+      safe true
+
+      # This generator should be passive with regard to its execution
+      priority :lowest
+
+      # Determine if pagination task is enabled
+      # 
+      # site - the Jekyll::Site object
+      #
+      # Returns true if pagination_task is enabled, false otherwise
+      def self.enabled?(site)
+        !site.config['pagination_task'].nil? && (site.pages.size > 0)
+      end
+
+      # Generate paginated pages if necessary.
+      #
+      # site - The Site.
+      #
+      # Returns nothing.
+      def generate(site)
+        if PaginationTask.enabled?(site)
+          if pagers = candidate_pagers(site)
+            pagers.each { |pager| site.pages.delete(pager) } 
+            pagers.each { |pager| paginate(site, pager) }
+          end
+        end
+      end
+
+      # Get the filter
+      #
+      # site - the Jekyll::Site object
+      #
+      # return - the instance of the filter
+      def get_filter(site, pager)
+        page_filter_class = pager['filter_class']
+        site_filter_class = site.config['pagination_task']['filter_class']
+        class_name = page_filter_class || site_filter_class
+
+        if class_name.nil? || !Object.const_defined?(class_name)
+          DefaultPaginationFilter.new(site, pager)
+        else
+          Object.const_get(class_name).new(site, pager)
+        end
+      end
+
+      def create_pager(site, template, pager)
+        instance = template.dup
+        instance.basename = "index"
+        instance.dir = PTPager.paginate_path(site, template, pager.page)
+        instance.pager = pager
+        instance.data['paginated'] = true
+
+        instance
+      end
+
+      # Paginates the blog's pages.
+      # 
+      # site - The Site.
+      # template - The pager template that defines a pagination.
+      #
+      def paginate(site, template)
+        post_only = site.config['pagination_task']['post_only'] || true
+        all_pages = []
+        if !YAML.load(post_only.to_s)
+          Jekyll.logger.info 'here'
+          all_pages += site.pages.select{ | page | !page['paginated'] }
+        end
+        all_pages += site.posts
+        filter = get_filter(site, template)
+        
+        if filter.nil?
+          Jekyll.logger.warn "Failed to create filter for page " + pager.url
+          return
+        end
+        all_pages = all_pages.select{ | page | filter.satisfy?(page) }
+        
+        page_per_pager = template['page_per_pager']
+        page_per_pager = page_per_pager || site.config['pagination_task']['page_per_pager']
+        page_per_pager = page_per_pager || 7
+
+        npages = Paginate::Pager.calculate_pages(all_pages, page_per_pager.to_i)
+        (1..npages).each do |num_page|
+          pager = PTPager.new(site, template, num_page, all_pages, page_per_pager.to_i)
+          site.pages << create_pager(site, template, pager)
+        end
+      end
+
+      # Public: Find the Jekyll::Page which will act as the pager template
+      #
+      # site - the Jekyll::Site object
+      #
+      # Returns the Jekyll::Page which will act as the pager template
+      def candidate_pagers(site)
+        site.pages.select { |page| (page['paginate'] || false ) === true }
+      end
+    end
+  end
+
+  class PTPager < Paginate::Pager
+
+    # Get the path for the generated pagers
+    #
+    # site - the Jekyll::Site object
+    # pager - the template for the pager
+    def self.paginate_path(site, pager, page_num)
+      return nil if page_num.nil?
+      format = pager['pagination_format']
+      format = format || site.config['pagination_task']['format']
+      format = format || '/:dir/:name/:Num'
+      dir = remove_leading_slash(pager.dup.dir)
+      name = File.basename(pager.name, File.extname(pager.name))
+      format = format.sub(':dir', dir)
+      format = format.sub(':name', name)
+      format = format.sub(':num', page_num.to_s)
+      format = page_num > 1 ? format.sub(':Num', page_num.to_s) : format.sub(':Num', '')
+      ensure_leading_slash(format)
+    end
+
+    # Initialize a new PTPager.
+    #
+    # site     - the Jekyll::Site object
+    # pager    - the pager template page
+    # current  - The Integer page number.
+    # all_posts - The Array of all the site's Posts.
+    # num_pages - The Integer number of pages or nil if you'd like the number
+    #             of pages calculated.
+    def initialize(site, pager, current, all_posts, per_page)
+      super(site, current, all_posts, Paginate::Pager.calculate_pages(all_posts, per_page))
+
+      @per_page = per_page
+      init = (@page - 1) * @per_page
+      offset = (init + @per_page - 1) >= all_posts.size ? all_posts.size : (init + @per_page - 1)
+
+      @posts = all_posts[init..offset]
+
+      @previous_page_path = PTPager.paginate_path(site, pager, @previous_page)
+      @next_page_path = PTPager.paginate_path(site, pager, @next_page)
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-pagination-task
+version: !ruby/object:Gem::Version
+  version: 1.0.3
+platform: ruby
+authors:
+- Kai Gao
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll-paginate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+description: ! "    Jekyll Pagination Task allows you to create paginated pages by\n
+  \   defining filters on attributes of all Jekyll pages.'\n"
+email: emiapwil@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- LICENSE
+- README.md
+- jekyll-pagination-task.gemspec
+- lib/jekyll-pagination-task.rb
+- lib/jekyll-pagination-task/pagination_task.rb
+homepage: http://github.com/emiapwil/jekyll-pagination-task
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: An advanced paginator for Jekyll
+test_files: []