jekyll-paginate-v2 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a7da34c28f9aa75d455021554bcd12dc1efd8ea
-  data.tar.gz: 19a37f789f35926c1a150389d9bb45bdc7162f64
+  metadata.gz: d2c5d1cedeea26a437e352ed736ea9f794e2b9c3
+  data.tar.gz: b566918809647d4dbc92aef957a8c30f70a17acc
 SHA512:
-  metadata.gz: cedfe9b72ca218c52648461e37b8c74b1e061113cfb55278cff2d74d3b1ed55c58d32e9929ea9f971823d5cfddc514304999d65266f03ac83461e871baf8cc3e
-  data.tar.gz: a81ac4c6c64925a6eaa346ca925e44f92abd948e3b70f1f57780088c441bff736de67ae81ff1992a7cfb13df426c32bc6e62e8605769287c077bf003e5dea522
+  metadata.gz: 39e3bfcbe0350ab850b2881f5c14507f82f36c910372fd2eb1e1fcd3270115f6f8779c125aa147d4b3a190a6fa91eb70cad5daf68f39704d0518995eb1c24792
+  data.tar.gz: 858eb0f571516a94a5926c40b804ec62c8d28ed5032b2ced95780cfa9371498ecd3b3219a8cfffbe02c382a7b41ac4b73ac008f2dcb9a900801f8fc7f83ee69d

data/README-GENERATOR.md

@@ -26,6 +26,8 @@ The **Generator** forms the core of the pagination logic. It is responsible for
 * [How to detect auto-generated pages](#detecting-generated-pagination-pages)
 * [Formatting page titles](#formatting-page-titles)
 * [Reading pagination meta information](#reading-pagination-meta-information)
+* [How to generate a JSON API](#generating-a-json-api)
+* [Renaming pagination file names](#renaming-pagination-file-names)
 * [Common issues](#common-issues)
     - [Dependency Error after installing](#i-keep-getting-a-dependency-error-when-running-jekyll-serve-after-installing-this-gem)
     - [Bundler error upgrading gem (Bundler::GemNotFound)](#im-getting-a-bundler-error-after-upgrading-the-gem-bundlergemnotfound)
@@ -89,6 +91,14 @@ pagination:
     before: 2
     after: 2
 
+  # Optional, the default file extension for generated pages (e.g html, json, xml).
+  # Internally this is set to html by default
+  extension: html
+
+  # Optional, the default name of the index file for generated pages (e.g. 'index.html')
+  # Without file extension
+  indexpage: 'index'
+
 ############################################################
 ```
 
@@ -481,6 +491,107 @@ Below is an example on how to print out a "Page x of n" in the pagination layout
 <h2>Page {{page.pagination_info.curr_page}} of {{page.pagination_info.total_pages}}</h2>
 ```
 
+## Generating a JSON API
+
+Delivering content via an API is useful, for a lot of the same reasons that pagination is useful. We want to delivery content, in such a way, that is:
+
+1. Easy for the user to consume.
+2. Easy for the browser to load.
+
+Paginating content meets both of these requirements, but developers are limited to presenting content statically rather than dynamically. Some example of dynamic content delivery are:
+- Pop up modals
+- Infinite scrolling
+- Multi-tiered pagination (e.g. Netflix UI horizontal scrolling for multiple movie categories)
+
+### So how do I generate a JSON API for Jekyll?
+
+First, create a new jekyll page and set its layout to `null` to avoid any extra html to show up.
+
+Next, use the `extension` and `indexpage` option to customize the output of the page and its paginated content as JSON files.
+
+Here's an example page:
+```
+---
+layout: null
+permalink: /api
+pagination:
+  permalink: 'feed-:num'
+  enabled: true
+  extension: json
+  indexpage: 'feed-1'
+---
+
+{
+  "pages": [{% for post in paginator.posts %}
+    {% if forloop.first != true %},{% endif %}
+    {
+      "title": "{{ post.title }}",
+      "link": "{{ post.url }}"
+    }{% endfor %}
+  ]
+}
+```
+Next, run `jekyll build`. This will generate a set of paginated JSON files under the folder `/api`. These JSON files can be loaded via Javascript/AJAX to dynamically load content into your site.
+
+Below's an example set of routes that the configuration would generate:
+- http://localhost:4000/api/feed-1.json
+- http://localhost:4000/api/feed-2.json
+- http://localhost:4000/api/feed-3.json
+
+And here is an example of one of the feed.json files that are created given the markup above
+```
+{
+  "pages": [
+    {
+      "title": "Narcisse Snake Pits",
+      "link": "/2016/11/narcisse-snake-pits.html"
+    },{
+      "title": "Luft-Fahrzeug-Gesellschaft",
+      "link": "/2016/11/luft-fahrzeug-gesellschaft.html"
+    },{
+      "title": "Rotary engine",
+      "link": "/2016/11/rotary-engine.html"
+    }
+  ], 
+  "next": "/api/feed-11.json",
+  "prev": "/api/feed-9.json",
+  "first": "/api/feed-1.json"
+}
+```
+
+For further information see [Example 4](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples/04-jsonapi), that project can serve as a starting point for your experiments with this feature.
+
+### How did you generate those 'next', 'prev' and 'first' links?
+
+All the normal paginator variables can be used in these JSON feed files. You can use them to achive quite powerful features such as pre-loading and detecting when there are no more feeds to load. 
+
+```
+{% if paginator.next_page %}
+  ,"next": "{{ paginator.next_page_path }}"
+  {% endif %}
+  {% if paginator.last_page %}
+  ,"prev": "{{ paginator.last_page_path }}"
+  {% endif %}
+  {% if paginator.first_page %}
+  ,"first": "{{ paginator.first_page_path }}"
+  {% endif %}
+```
+
+## Renaming pagination file names
+By default the pagination system creates all paginated pages as `index.html`. The system provides an option to override this name and file extension with the 
+
+```yml
+  indexpage: index
+  extension: html
+```
+
+If you wanted to generate all pagination files as `default.htm` then the settings should be configured as follows
+
+```yml
+  indexpage: default
+  extension: htm
+```
+
 ## Common issues
 
 ### I keep getting a dependency error when running jekyll serve after installing this gem

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

@@ -82,7 +82,7 @@ module Jekyll
       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 )
+          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)

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

@@ -16,6 +16,8 @@ module Jekyll
           '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
       '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/paginationGenerator.rb

@@ -26,9 +26,10 @@ module Jekyll
         # 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 jekyll-paginate-v2 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."
+            err_msg = "The new jekyll-paginate-v2 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

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

@@ -262,6 +262,11 @@ module Jekyll
         # list of all newly created pages
         newpages = []
 
+        # Consider the default index page name and extension
+        indexPageName = config['indexpage'].split('.')[0]
+        indexPageExt = Utils.ensure_leading_dot(config['extension'])
+        indexPageWithExt = indexPageName + indexPageExt
+
         # 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
@@ -269,7 +274,7 @@ module Jekyll
 
           # 1. Create the in-memory page
           #    External Proc call to create the actual page for us (this is passed in when the pagination is run)
-          newpage = PaginationPage.new( template, cur_page_nr, total_pages )
+          newpage = PaginationPage.new( template, cur_page_nr, total_pages, indexPageWithExt )
 
           # 2. Create the url for the in-memory page (calc permalink etc), construct the title, set all page.data values needed
           paginated_page_url = config['permalink']
@@ -282,17 +287,17 @@ module Jekyll
           paginated_page_url = File.join(first_index_page_url, paginated_page_url)
           
           # 3. Create the pager logic for this page, pass in the prev and next page numbers, assign pager to in-memory page
-          newpage.pager = Paginator.new( config['per_page'], first_index_page_url, paginated_page_url, using_posts, cur_page_nr, total_pages)
+          newpage.pager = Paginator.new( config['per_page'], first_index_page_url, paginated_page_url, using_posts, cur_page_nr, total_pages, indexPageName, indexPageExt)
 
           # Create the url for the new page, make sure we prepend any permalinks that are defined in the template page before
           if newpage.pager.page_path.end_with? '/'
-            newpage.set_url(File.join(newpage.pager.page_path, 'index.html'))
-          elsif newpage.pager.page_path.end_with? '.html'
+            newpage.set_url(File.join(newpage.pager.page_path, indexPageWithExt))
+          elsif newpage.pager.page_path.end_with? indexPageExt
             # Support for direct .html files
             newpage.set_url(newpage.pager.page_path)
           else
             # Support for extensionless permalinks
-            newpage.set_url(newpage.pager.page_path+'.html')
+            newpage.set_url(newpage.pager.page_path+indexPageExt)
           end
 
           if( template.data['permalink'] )

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

@@ -9,13 +9,15 @@ module Jekyll
     # This page exists purely in memory and is not read from disk
     #
     class PaginationPage < Page
-      def initialize(page_to_copy, cur_page_nr, total_pages)
+      def initialize(page_to_copy, cur_page_nr, total_pages, index_pageandext)
         @site = page_to_copy.site
         @base = ''
         @url = ''
+        @name = index_pageandext.nil? ? 'index.html' : index_pageandext
+
+        self.process(@name) # Creates the basename and ext member values
 
         # Only need to copy the data part of the page as it already contains the layout information
-        #self.data = Marshal.load(Marshal.dump(page_to_copy.data)) # Deep copying, http://stackoverflow.com/a/8206537/779521
         self.data = Jekyll::Utils.deep_merge_hashes( page_to_copy.data, {} )
         if !page_to_copy.data['autopage']
           self.content = page_to_copy.content
@@ -28,14 +30,7 @@ module Jekyll
         end
 
         # Store the current page and total page numbers in the pagination_info construct
-        self.data['pagination_info'] = {"curr_page" => cur_page_nr, 'total_pages' => total_pages }
-
-        # Set the page extension
-        extension = self.data['pagination']['extension']
-        extension = extension.nil? ? '.html': '.' + extension
-        @name = 'index' + extension
-
-        self.process(@name) # Creates the basename and ext member values
+        self.data['pagination_info'] = {"curr_page" => cur_page_nr, 'total_pages' => total_pages }       
 
         # Perform some validation that is also performed in Jekyll::Page
         validate_data! page_to_copy.path

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

@@ -19,7 +19,7 @@ module Jekyll
       
       # Initialize a new Paginator.
       #
-      def initialize(config_per_page, first_index_page_url, paginated_page_url, posts, cur_page_nr, num_pages)
+      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
@@ -31,6 +31,24 @@ module Jekyll
         init = (@page - 1) * @per_page
         offset = (init + @per_page - 1) >= posts.size ? posts.size : (init + @per_page - 1)
 
+        # Adjust the first index page url
+        if( first_index_page_url.end_with?('/'))
+          first_index_page_url = first_index_page_url + default_indexpage + default_ext
+          puts "Appending default index+ext: #{first_index_page_url}"
+        elsif !first_index_page_url.include?('.')
+          first_index_page_url = first_index_page_url + default_indexpage
+          puts "Appending default index only: #{first_index_page_url}"
+        end
+
+        # Adjust the paginated pages as well
+        if( paginated_page_url.end_with?('/'))
+          paginated_page_url = paginated_page_url + default_indexpage + default_ext
+          puts "Appending default paginated index+ext: #{paginated_page_url}"
+        elsif !paginated_page_url.include?('.')
+          paginated_page_url = paginated_page_url + default_ext
+          puts "Appending default paginated ext only: #{paginated_page_url}"
+        end
+
         @total_posts = posts.size
         @posts = posts[init..offset]
         @page_path = @page == 1 ? first_index_page_url : Utils.format_page_number(paginated_page_url, cur_page_nr, @total_pages)

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

@@ -32,6 +32,17 @@ module Jekyll
       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 version of the input which has a leading slash.
       #         If the input already has a forward slash in position zero, it will be

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

@@ -1,8 +1,8 @@
 module Jekyll
   module PaginateV2
-    VERSION = "1.8.2"
+    VERSION = "1.9.0"
     # When modifying remember to issue a new tag command in git before committing, then push the new tag
-    #   git tag -a v1.8.2 -m "Gem v1.8.2"
+    #   git tag -a v1.9.0 -m "Gem v1.9.0"
     #   git push origin --tags
     # Yanking a published Gem
     #   gem yank jekyll-paginate-v2 -v VERSION

data/spec/generator/paginator_spec.rb

@@ -6,7 +6,7 @@ module Jekyll::PaginateV2::Generator
     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)
+      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
@@ -22,10 +22,10 @@ module Jekyll::PaginateV2::Generator
     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) }.must_raise RuntimeError
+      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)
+      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
@@ -35,7 +35,7 @@ module Jekyll::PaginateV2::Generator
       # 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 = Paginator.new(5, "index.html", "/page:num/", posts, 2, 5, '', '')
 
       pager.page.must_equal 2
       pager.per_page.must_equal 5
@@ -60,7 +60,7 @@ module Jekyll::PaginateV2::Generator
       # Initialize a pager with
       #   5 posts per page
       #   at page 2 out of 5 pages
-      pager = Paginator.new(5, "index.html", "/page:num/", posts, 1, 5)
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 1, 5, '', '')
 
       pager.page.must_equal 1
       pager.per_page.must_equal 5
@@ -85,7 +85,7 @@ module Jekyll::PaginateV2::Generator
       # Initialize a pager with
       #   5 posts per page
       #   at page 2 out of 5 pages
-      pager = Paginator.new(5, "index.html", "/page:num/", posts, 5, 5)
+      pager = Paginator.new(5, "index.html", "/page:num/", posts, 5, 5, '', '')
 
       pager.page.must_equal 5
       pager.per_page.must_equal 5
@@ -103,5 +103,55 @@ module Jekyll::PaginateV2::Generator
       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, "/", "/feed:num", posts, 2, 5, 'feed', '.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 '/feed.json'
+      pager.next_page.must_equal 3
+      pager.next_page_path.must_equal '/feed3.json'
+    end
+
   end
 end

metadata

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