jekyll-paginate-v2 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49eff43d9fc82a1291afa41a9375f5e4892dd977
-  data.tar.gz: 9446fed7b472bb42b50d16f0e4f718aa38fe220d
+  metadata.gz: 520aefbd27b59fcb86fcaca7871c693295bafb16
+  data.tar.gz: 3e45a7ccc457134a43ee81520dc0f32971c9989d
 SHA512:
-  metadata.gz: 6ed1b856077d5f7fb1ccd9e3839adf8264167ac2a09b73b095b1d54157929ad0d8df283aadfcb4edccb8993a97bd6556ba909f6a703d6aa6c1391a4b459ece33
-  data.tar.gz: 9da8d889d46921e8d792399da5be7ee832691a1f1d823ee178f351a60e6428860f38d0e5d5c13fba4cb279c19b9fce82c3a6b796f0a7a221fc373f2eb626bff9
+  metadata.gz: 31e6855bc99cd94c7160da6e5926046f7cb32b783bd177c9b5ef1d3d38b989063746df296a3909159e3fbc43d9285202d424d165ef639c0187c002828b8ff332
+  data.tar.gz: 734e0a050c950f4535c49eb115009f65c509ecd20ce8c1c95b99b27fa535bef19f8a990457edd8a9e1207184004f617d84e416385bf1602c73af28470af51532

data/README-GENERATOR.md

@@ -22,6 +22,7 @@ The **Generator** forms the core of the pagination logic. It is responsible for
 * [How to paginate on combination of filters](#paginate-on-combination-of-filters)
 * [Overriding site configuration](#configuration-overrides)
 * [Advanced Sorting](#advanced-sorting)
+* [Creating Pagination Trails](#creating-pagination-trails)
 * [How to detect auto-generated pages](#detecting-generated-pagination-pages)
 * [Formatting page titles](#formatting-page-titles)
 * [Common issues](#common-issues)
@@ -79,6 +80,14 @@ pagination:
   # in reality this can be any value, suggested are the Microsoft locale-codes (e.g. en_US, en_GB) or simply the ISO-639 language code )
   locale: '' 
 
+ # Optional,omit or set both before and after to zero to disable. 
+ # Controls how the pagination trail for the paginated pages look like. 
+ # this feature enables the user to display a <prev, 1, 2, 3, 4, 5, next> pagination trail on their page
+ # By default this feature produces two pages before and two pages after the current page (total of 5 pages)
+  trail: 
+    before: 2
+    after: 2
+
 ############################################################
 ```
 
@@ -356,6 +365,58 @@ pagination:
 ---
 ```
 
+## Creating Pagination Trails
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sverrirs/jekyll-paginate-v2/master/res/pagination-trails.png" width="59" />
+</p>
+
+Creating a trail structure for your pagination as shown above can be achieved by enabling the `trail` configuration and including a little extra code in your liquid templates.
+
+``` yml
+pagination:
+  trail: 
+    before: 2 # The number of links before the current page
+    after: 2  # The number of links after the current page
+```
+
+Your layout file would then have to include code similar to the following to generate the correct HTML structure
+
+``` HTML
+{% if paginator.page_trail %}
+  {% for trail in paginator.page_trail %}
+    <li>
+        <a href="{{ trail.path | prepend: site.baseurl }}" title="{{trail.title}}">{{ trail.num }}</a>
+    </li>
+  {% endfor %}
+{% endif %}
+```
+
+The `trail` value exposes three properties:
+* `num`: The number of the page
+* `path`: The path to the page
+* `title`: The title of the page
+
+The algorithm will always attempt to keep the same trail length for all pages (`trail length = before + after + 1`). 
+Example when on page 4 the trail for the configuration above would look like this
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sverrirs/jekyll-paginate-v2/master/res/pagination-trails-p4.png" />
+</p>
+
+Different number of before and after trail links can be specified. Below is an example of how this yml config would look like when on the same page 4
+
+``` yml
+pagination:
+  trail: 
+    before: 1
+    after: 3
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sverrirs/jekyll-paginate-v2/master/res/pagination-trails-p4-b1a3.png" />
+</p>
+
 ## Detecting generated pagination pages
 
 To identify the auto-generated pages that are created by the pagination logic when iterating through collections such as `site.pages` the `page.autogen` variable can be used like so

data/lib/jekyll-paginate-v2/generator/defaults.rb

@@ -12,6 +12,10 @@ module Jekyll
       '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)
+      },
       'debug'        => false, # Turns on debug output for the gem
       'legacy'       => false # Internal value, do not use (will be removed after 2018-01-01)
     }

data/lib/jekyll-paginate-v2/generator/paginationModel.rb

@@ -235,6 +235,9 @@ module Jekyll
         #### BEFORE STARTING REMOVE THE TEMPLATE PAGE FROM THE SITE LIST!
         @page_remove_lambda.call( template )
         
+        # list of all newly created pages
+        newpages = []
+
         # Now for each pagination page create it and configure the ranges for the collection
         # This .pager member is a built in thing in Jekyll and defines the paginator implementation
         # Simpy override to use mine
@@ -284,7 +287,38 @@ module Jekyll
           
           # Add the page to the site
           @page_add_lambda.call( newpage )
-        end
+
+          # Store the page in an internal list for later referencing if we need to generate a pagination number path later on
+          newpages << newpage
+        end #each.do total_pages
+
+        # Now generate the pagination number path, e.g. so that the users can have a prev 1 2 3 4 5 next structure on their page
+        # simplest is to include all of the links to the pages preceeding the current one
+        # (e.g for page 1 you get the list 2, 3, 4.... and for page 2 you get the list 3,4,5...)
+        if( config['trail'] && !config['trail'].nil? && newpages.size.to_i > 1 )
+          trail_before = [config['trail']['before'].to_i, 0].max
+          trail_after = [config['trail']['after'].to_i, 0].max
+          trail_length = trail_before + trail_after + 1
+
+          if( trail_before > 0 || trail_after > 0 )
+            newpages.select do | npage |
+              idx_start = [ npage.pager.page - trail_before - 1, 0].max # Selecting the beginning of the trail
+              idx_end = [idx_start + trail_length, newpages.size.to_i].min # Selecting the end of the trail
+
+              # Always attempt to maintain the max total of <trail_length> pages in the trail (it will look better if the trail doesn't shrink)
+              if( idx_end - idx_start < trail_length )
+                # Attempt to pad the beginning if we have enough pages
+                idx_start = [idx_start - ( trail_length - (idx_end - idx_start) ), 0].max # Never go beyond the zero index
+              end              
+
+              # Convert the newpages array into a two dimensional array that has [index, page_url] as items
+              #puts( "Trail created for page #{npage.pager.page} (idx_start:#{idx_start} idx_end:#{idx_end})")
+              npage.pager.page_trail = newpages[idx_start...idx_end].each_with_index.map {|ipage,idx| PageTrail.new(idx_start+idx+1, ipage.pager.page_path, ipage.data['title'])}
+              #puts( npage.pager.page_trail )
+            end #newpages.select
+          end #if trail_before / trail_after
+        end # if config['trail']
+
       end # function paginate
 
     end # class PaginationV2

data/lib/jekyll-paginate-v2/generator/paginator.rb

@@ -6,7 +6,15 @@ module Jekyll
     #
     class Paginator
       attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
-        :previous_page, :previous_page_path, :next_page, :next_page_path, :page_path
+        :previous_page, :previous_page_path, :next_page, :next_page_path, :page_path, :page_trail
+
+      def page_trail
+        @page_trail
+      end
+
+      def page_trail=(page_array)
+        @page_trail = page_array
+      end
       
       # Initialize a new Paginator.
       #
@@ -45,11 +53,32 @@ module Jekyll
           'previous_page' => previous_page,
           'previous_page_path' => previous_page_path,
           'next_page' => next_page,
-          'next_page_path' => next_page_path
+          'next_page_path' => next_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+"index.html",
+          'title' => title
+        }
+      end
+    end #class PageTrail
+
   end # module PaginateV2
 end # module Jekyll

data/lib/jekyll-paginate-v2/version.rb

@@ -1,8 +1,8 @@
 module Jekyll
   module PaginateV2
-    VERSION = "1.6.1"
+    VERSION = "1.7.0"
     # When modifying remember to issue a new tag command in git before committing, then push the new tag
-    # git tag -a v1.6.1 -m "Gem v1.6.1"
+    # git tag -a v1.7.0 -m "Gem v1.7.0"
     # git push origin --tags
   end # module PaginateV2
 end # module Jekyll

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-paginate-v2
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Sverrir Sigmundarson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-24 00:00:00.000000000 Z
+date: 2017-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll