Merge branch 'dev'

ddnexus · Aug 20, 2019 · 2f7a346 · 2f7a346
2 parents da3fc37 + 5178acc
commit 2f7a346
Show file tree

Hide file tree

Showing 24 changed files with 352 additions and 48 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.idea/
diff --git a/.travis.yml b/.travis.yml
@@ -43,10 +43,10 @@ matrix:
         - RUN_CODECOV=true
 
     # jruby
-    - rvm: jruby-1.7
-      gemfile: gemfiles/ruby-1.9
-    - rvm: jruby-9.0
-      gemfile: gemfiles/ruby-2.0
+#    - rvm: jruby-1.7
+#      gemfile: gemfiles/ruby-1.9
+#    - rvm: jruby-9.0
+#      gemfile: gemfiles/ruby-2.0
     - rvm: jruby-9.1
     - rvm: jruby-9.2
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,26 @@
 # CHANGELOG
 
+## Version 3.5.0
+
+### Changes
+
+- Added Korean locale
+- Added Catalan locale
+- Added metadata extra
+- Docs fixes and improvements
+
+### Commits
+
+- [2813973](http://github.com/ddnexus/pagy/commit/2813973): Docs:
+    - added detailed Quick Start steps (closes #176, closes #177)
+    - added specific sections for API clients and javascript frameworks
+- [43349a8](http://github.com/ddnexus/pagy/commit/43349a8): added metadata extra
+- [261e6e6](http://github.com/ddnexus/pagy/commit/261e6e6): Add Catalan localization (#178)
+- [30ed505](http://github.com/ddnexus/pagy/commit/30ed505): temporarily removed jruby 1.7 and 9.0 rvm from travis - waiting travis to fix their rvms or suggest some work around [see issue](https://travis-ci.community/t/jruby-1-7-and-9-0-fail/4703)
+- [2863c55](http://github.com/ddnexus/pagy/commit/2863c55): added minitest-reporters gem
+- [0b42e5c](http://github.com/ddnexus/pagy/commit/0b42e5c): Add translation ko.yml for korean (#172)
+- [da3fc37](http://github.com/ddnexus/pagy/commit/da3fc37): minor doc fixes [ci skip]
+
 ## Version 3.4.1
 
 ### Changes

diff --git a/Gemfile b/Gemfile
@@ -5,6 +5,7 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 # test
 gem 'rake'
 gem 'minitest'
+gem 'minitest-reporters'
 gem 'rack'
 gem 'i18n'
 

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -8,7 +8,9 @@ GEM
       tzinfo (~> 1.1)
     addressable (2.5.2)
       public_suffix (>= 2.0.2, < 4.0)
+    ansi (1.5.0)
     ast (2.4.0)
+    builder (3.2.3)
     codecov (0.1.14)
       json
       simplecov
@@ -212,6 +214,11 @@ GEM
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.11.3)
+    minitest-reporters (1.3.6)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
     multipart-post (2.0.0)
     nokogiri (1.10.3)
       mini_portile2 (~> 2.4.0)
@@ -279,6 +286,7 @@ DEPENDENCIES
   github-pages (= 197)
   i18n
   minitest
+  minitest-reporters
   oj
   rack
   rake

diff --git a/README.md b/README.md
@@ -106,6 +106,8 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 - [array](http://ddnexus.github.io/pagy/extras/array): Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding
 - [countless](http://ddnexus.github.io/pagy/extras/countless): Paginate without the need of any count, saving one query per rendering
 - [elasticsearch_rails](http://ddnexus.github.io/pagy/extras/elasticsearch_rails): Paginate `ElasticsearchRails` response objects
+- [headers](http://ddnexus.github.io/pagy/extras/headers): Add RFC-8288 compliant http response headers (and other helpers) useful for API pagination
+- [metadata](http://ddnexus.github.io/pagy/extras/metadata): Provides the pagination metadata to Javascrtipt frameworks like Vue.js, react.js, etc.
 - [searchkick](http://ddnexus.github.io/pagy/extras/searchkick): Paginate `Searchkick::Results` objects
 
 ### Frontend Extras
@@ -120,7 +122,6 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 
 ### Feature Extras
 
-- [headers](http://ddnexus.github.io/pagy/extras/headers): Add RFC-8288 compliant http response headers (and other helpers) useful for API pagination
 - [i18n](http://ddnexus.github.io/pagy/extras/i18n): Use the `I18n` gem instead of the pagy-i18n implementation
 - [items](http://ddnexus.github.io/pagy/extras/items): Allow the client to request a custom number of items per page with an optional selector UI
 - [overflow](http://ddnexus.github.io/pagy/extras/overflow): Allow for easy handling of overflowing pages

diff --git a/Rakefile b/Rakefile
@@ -12,7 +12,8 @@ require "rake/testtask"
 Rake::TestTask.new(:test_main) do |t|
   t.libs += %w[test lib]
   t.test_files = FileList.new.include("test/**/*_test.rb")
-                             .exclude('test/**/i18n_test.rb',
+                             .exclude('test/**/headers_test.rb',
+                                      'test/**/i18n_test.rb',
                                       'test/**/items_test.rb',
                                       'test/**/overflow_test.rb',
                                       'test/**/trim_test.rb',
@@ -23,6 +24,11 @@ Rake::TestTask.new(:test_main) do |t|
                                       'test/**/shared_combo_test.rb')
 end
 
+Rake::TestTask.new(:test_extra_headers) do |t|
+  t.libs += %w[test lib]
+  t.test_files = FileList['test/**/headers_test.rb']
+end
+
 Rake::TestTask.new(:test_extra_i18n) do |t|
   t.libs += %w[test lib]
   t.test_files = FileList['test/**/i18n_test.rb']
@@ -66,6 +72,7 @@ end
 
 task :test => [ :test_main,
                 :test_extra_items,
+                :test_extra_headers,
                 :test_extra_i18n,
                 :test_extra_overflow,
                 :test_extra_trim,

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -110,6 +110,7 @@ <h1 id="site-title">{{ site.title | default: site.github.repository_name }}
       <a href="{{ site.baseurl }}/extras/items"><p class="indent1" {% if page.title == 'Items' %}id="active"{% endif %} >Items</p></a>
       <a href="{{ site.baseurl }}/extras/overflow"><p class="indent1" {% if page.title == 'Overflow' %}id="active"{% endif %} >Overflow</p></a>
       <a href="{{ site.baseurl }}/extras/materialize"><p class="indent1" {% if page.title == 'Materialize' %}id="active"{% endif %} >Materialize</p></a>
+      <a href="{{ site.baseurl }}/extras/metadata"><p class="indent1" {% if page.title == 'Metadata' %}id="active"{% endif %} >Metadata</p></a>
       <a href="{{ site.baseurl }}/extras/navs"><p class="indent1" {% if page.title == 'Navs' %}id="active"{% endif %} >Navs</p></a>
       <a href="{{ site.baseurl }}/extras/searchkick"><p class="indent1" {% if page.title == 'Searchkick' %}id="active"{% endif %} >Searchkick</p></a>
       <a href="{{ site.baseurl }}/extras/semantic"><p class="indent1" {% if page.title == 'Semantic' %}id="active"{% endif %} >Semantic</p></a>

diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
@@ -6,6 +6,8 @@
 body {
   background-color: #f7f7f7;
   color: #51585F;
+  padding-top: 30px;
+  padding-bottom: 30px;
 }
 
 a:hover, a:focus {

diff --git a/docs/extras.md b/docs/extras.md
@@ -17,13 +17,14 @@ Pagy comes with a few optional extensions/extras:
 | `i18n`                | Use the `I18n` gem instead of the pagy implementation                                                                                      | [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i81n.rb), [documentation](extras/i18n.md)                                              |
 | `items`               | Allow the client to request a custom number of items per page with a ready to use selector UI                                              | [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb), [documentation](extras/items.md)                                           |
 | `materialize`         | Add nav, nav_js and combo_nav_js helpers for the Materialize CSS [pagination component](https://materializecss.com/pagination.html)        | [materialize.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/materialize.rb), [documentation](extras/materialize.md)                         |
+| `metadata`            | Provides the pagination metadata to Javascrtipt frameworks like Vue.js, react.js, etc.                                                     | [metadata.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/metadata.rb), [documentation](extras/metadata.md)                                  |
 | `navs`                | Add nav_js and combo_nav_js javascript unstyled helpers                                                                                    | [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb), [documentation](extras/navs.md)                                              |
 | `overflow`            | Allow for easy handling of overflowing pages                                                                                               | [overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb), [documentation](extras/overflow.md)                                  |
 | `searchkick`          | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding                                                       | [searchkick.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/searchkick.rb), [documentation](extras/searchkick.md)                            |
 | `semantic`            | Add nav, nav_js and combo_nav_js helpers for the Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html)     | [semantic.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/semantic.rb), [documentation](extras/semantic.md)                                  |
 | `support`             | Extra support for features like: incremental, infinite, auto-scroll pagination                                                             | [support.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/support.rb), [documentation](extras/support.md)                                     |
 | `trim`                | Remove the `page=1` param from links                                                                                                       | [trim.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/trim.rb), [documentation](extras/trim.md)                                              |
-| `uikit`               | Add nav, nav_js and combo_nav_js helpers for the UIkit [pagination component](https://getuikit.com/docs/pagination)                                                  | [uikit.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/uikit.rb), [documentation](extras/uikit.md)                                           |
+| `uikit`               | Add nav, nav_js and combo_nav_js helpers for the UIkit [pagination component](https://getuikit.com/docs/pagination)                        | [uikit.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/uikit.rb), [documentation](extras/uikit.md)                                           |
 
 ## Synopsis
 

diff --git a/docs/extras/headers.md b/docs/extras/headers.md
@@ -127,8 +127,10 @@ This method generates a hash of [RFC-8288](https://tools.ietf.org/html/rfc8288)
 
 ### pagy_headers_hash(pagy)
 
-This method generates a hash structure of the headers, useful if you want to include some meta-data within your json. For example:
+This method generates a hash structure of the headers, useful only if you want to include the headers as metadata within your JSON. For example:
 
 ```ruby
 render json: records.as_json.merge!(meta: {pagination: pagy_headers_hash(pagy)})
 ```
+
+**Notice**: If you need a more complete set of metadata (e.g. if you use some javascript frontend) see the [metadata extra](metadata.md).
diff --git a/docs/extras/metadata.md b/docs/extras/metadata.md
@@ -0,0 +1,66 @@
+---
+title: Metadata
+---
+# Metadata Extra
+
+If your app uses ruby as pure backend and some javascript frameworks as the frontend (e.g. Vue.js, react.js, ...), then you may want to generate the whole pagination UI directly in javascript either with your own code or using some available component.
+
+This extra makes that easy and efficient by adding a single method to the backend.
+
+## Synopsis
+
+See [extras](../extras.md) for general usage info.
+
+In the `pagy.rb` initializer:
+
+```ruby
+require 'pagy/extras/metadata'
+```
+
+In your controller action:
+
+```ruby
+pagy, records = pagy(Product.all)
+render json: { data: records,
+               pagy: pagy_metadata(pagy) }
+```
+
+## Files
+
+- [hash.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/metadata.rb)
+
+## Variables
+
+| Variable    | Description                                          | Default                                                                                                                                                                                  |
+|:------------|:-----------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `:metadata` | Array of names used to control the returned metadata | `[ :scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url, :count, :page, :items, :vars, :pages, :last, :from, :to, :prev, :next, :series ]` (plus `:sequels` if defined) |
+
+As usual, depending on the scope of the customization, you can set the `:metadata` variable globally or for a single pagy instance.
+
+**IMPORTANT**: Don't rely on the broad default! You should explicitly set the `:metadata` variable with only the names that you will actually use in the frontend, for obvious performance reasons.
+
+### :scaffold_url key
+
+This is a special url string that you can use as the scaffold to build real page urls in your frontend (instead of producing them on the backend).
+
+It is a pagination url/path (complete with all the params) containing the `__pagy_page__` placeholder in place of the page number (e.g. `'/foo?page=__pagy_page__&bar=baz'`)
+
+You can generate all the actual links on the frontend by simply replacing the placeholder with the actual page number you want to link to.
+
+In javascript you can do something like:
+
+```js
+page_url = scaffold_url.replace(/__pagy_page__/, page_number)
+```
+
+This is particularly useful when you want to build some dynamic pagination UI (e.g. similar to what the `pagy_*combo_js` generates), but right in your frontend app, saving backend resources with obvious performance benefits.
+
+**Notice**: for simple cases you might directly use the other few `:*_url` metadata instead of the `:scaffold_url`.
+
+## Methods
+
+This extra adds a single method to the `Pagy::Backend` (available in your controllers).
+
+### pagy_metadata(pagy, url=false)
+
+This method returns a hash with the keys/values defined by the `:metadata` variable.  When true, the `url` boolean argument will cause all the `:*_url` metadata to be absolute instead of relative.
diff --git a/docs/extras/semantic.md b/docs/extras/semantic.md
@@ -1,5 +1,5 @@
 ---
-title: Semantic UI
+title: Semantic
 ---
 # Semantic UI Extra
 
@@ -46,4 +46,4 @@ See more details in the [javascript navs](navs.md#javascript-navs) documentation
 
 This method is the same as the `pagy_combo_nav_js`, but customized for the Semantic UI framework.
 
-See more details in the [compact_navs_js](navs.md#javascript-combo-navs)  documentation.
+See more details in the [compact_navs_js](navs.md#javascript-combo-navs) documentation.