Bulma extra (#62)

* Added Bulma extra helper
* Added templates for Bulma extra
* Added documentation for Bulma extra
* Added Bulma support for responsive extra
* Added Bulma support for compact extra
* Added information about bulma extra into README

README.md

@@ -87,6 +87,10 @@ Paginate arrays efficiently avoiding expensive array-wrapping and without any ov
 
 Nav helper and templates for Bootstrap pagination. _(see [more...](http://ddnexus.github.io/pagy/extras/bootstrap))_
 
+### Bulma Extra
+
+Nav helper and templates for Bulma CSS framework pagination. _(see [more...](http://ddnexus.github.io/pagy/extras/bulma))_
+
 ### Compact Extra
 
 An alternative UI that combines the pagination feature with the navigation info in one compact element. _(see [more...](http://ddnexus.github.io/pagy/extras/compact))_

docs/extras.md

@@ -9,6 +9,7 @@ Pagy comes with a few optional extensions/extras:
 | ------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
 | `array`      | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding                   | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md)                |
 | `bootstrap`  | Nav helper and templates for Bootstrap pagination                                                      | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md)    |
+| `bulma`      | Nav helper and templates for [Bulma](https://bulma.io) pagination component                            | [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb), [documentation](extras/bulma.md)                |
 | `compact`    | An alternative UI that combines the pagination  with the nav info in a single compact element          | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [documentation](extras/compact.md)          |
 | `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)                |

docs/extras/bulma.md

@@ -0,0 +1,46 @@
+---
+title: Bulma
+---
+# Bulma Extra
+
+This extra adds nav helper and templates for Bulma CSS framework [pagination component](https://bulma.io/documentation/components/pagination).
+
+## Synopsys
+
+See [extras](../extras.md) for general usage info.
+
+Render the navigation links in some view...
+with a fast helper:
+
+```erb
+<%== pagy_nav_bulma(@pagy) %>
+```
+
+or with a template:
+
+```erb
+<%== render 'pagy/nav_bulma', locals: {pagy: @pagy} %>
+```
+
+## Files
+
+This extra is composed of 4 files:
+
+- [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb)
+- [nav_bulma.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.erb) (optional template)
+- [nav_bulma.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.haml) (optional template)
+- [nav_bulma.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.slim)  (optional template)
+
+## Methods
+
+This extra adds one nav helpers to the `Pagy::Frontend` module. You can customize it by overriding it directly in your own view helper.
+
+### pagy_nav_bulma(pagy)
+
+This method is the same as the `pagy_nav`, but customized for Bulma.
+
+The `nav_bulma.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.
+
+### Optional Template Files
+
+See [Using Templates](../how-to.md#using-templates).

docs/extras/compact.md

@@ -22,6 +22,7 @@ Then use the responsive helper(s) in any view:
 ```erb
 <%== pagy_nav_compact(@pagy) %>
 <%== pagy_nav_compact_bootstrap(@pagy) %>
+<%== pagy_nav_compact_bulma(@pagy) %>
 ```
 
 ## Files
@@ -41,3 +42,10 @@ It can take an extra `id` argument, which is used to build the `id` attribute of
 ### pagy_nav_compact_bootstrap(pagy, ...)
 
 This method is the same as the `pagy_nav_compact`, but customized for Bootstrap.
+
+### pagy_nav_compact_bulma(pagy, ...)
+
+This method is the same as the `pagy_nav_compact`, but customized for Bulma CSS framework.
+
+Generated pagination preview:
+![pagy-compact-bulma](../assets/images/pagy-compact-bulma-g.png)

docs/extras/responsive.md

@@ -28,6 +28,7 @@ Then use the responsive helper(s) in any view:
 ```erb
 <%== pagy_nav_responsive(@pagy) %>
 <%== pagy_nav_responsive_bootstrap(@pagy) %>
+<%== pagy_nav_responsive_bulma(@pagy) %>
 ```
 
 ## Files
@@ -57,9 +58,9 @@ The `reponsive` extra adds an instance method to the `Pagy` class and couple of
 
 ### responsive
 
-**Notice**: Unless you are going to override a `pagy_nav_responsive` or `pagy_nav_responsive_bootstrap` helper you can ignore this method.
+**Notice**: Unless you are going to override a `pagy_nav_responsive*` helpers you can ignore this method.
 
-This is a `Pagy` instance method that returns the data structure used by the `pagy_nav_responsive` and `pagy_nav_responsive_bootstrap` helpers in order to build the html and the javascript codes needed to make Pagy responsive to different widths.
+This is a `Pagy` instance method that returns the data structure used by the `pagy_nav_responsive*` helpers in order to build the html and the javascript codes needed to make Pagy responsive to different widths.
 
 ### pagy_nav_responsive(pagy, ...)
 
@@ -70,3 +71,7 @@ It can take an extra `id` argument, which is used to build the `id` attribute of
 ### pagy_nav_responsive_bootstrap(pagy, ...)
 
 This method is the same as the `pagy_nav_responsive`, but customized for Bootstrap.
+
+### pagy_nav_responsive_bulma(pagy, ...)
+
+This method is the same as the `pagy_nav_responsive`, but customized for Bulma CSS framework.

lib/pagy/extras/bulma.rb

@@ -0,0 +1,37 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/bulma
+# frozen_string_literal: true
+
+class Pagy
+  # Add nav helper for Bulma pagination
+  module Frontend
+
+    def pagy_nav_bulma(pagy)
+      html, link, p_prev, p_next = +'', pagy_link_proc(pagy), pagy.prev, pagy.next
+
+      html << (p_prev ? link.call(p_prev, pagy_t('pagy.nav.prev'), 'class="pagination-previous" aria-label="previous page"')
+                      : %(<a class="pagination-previous" disabled>#{pagy_t('pagy.nav.prev')}</a>))
+      html << (p_next ? link.call(p_next, pagy_t('pagy.nav.next'), 'class="pagination-next" aria-label="next page"')
+                      : %(<a class="pagination-next" disabled>#{pagy_t('pagy.nav.next')}</a>))
+      html << '<ul class="pagination-list">'
+      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+        html << pagy_nav_bulma_item(link, item)
+      end
+      html << '</ul>'
+      %(<nav class="pagy-nav-bulma pagination is-centered" role="navigation" aria-label="pagination">#{html}</nav>)
+    end
+
+    private
+
+    def pagy_nav_bulma_item(link, item)
+      if item.is_a?(Integer)   # page link
+        aria = %( area-label="goto page #{item}")
+        %(<li>#{link.call item, item, 'class="pagination-link"' + aria}</li>)
+      elsif item.is_a?(String) # active page
+        aria = %( area-label="page #{item}" area-current="page")
+        %(<li>#{link.call item, item, 'class="pagination-link is-current"' + aria}</li>)
+      elsif item == :gap       # page gap
+        %(<li><span class="pagination-ellipsis">#{pagy_t('pagy.nav.gap')}</span></li>)
+      end
+    end
+  end
+end

lib/pagy/extras/compact.rb

@@ -38,5 +38,22 @@ def pagy_nav_compact_bootstrap(pagy, id=caller(1,1)[0].hash)
       html << %(</div></nav><script type="application/json" class="pagy-compact-json">["#{id}", "#{MARKER}", "#{p_page}"]</script>)
     end
 
+    # Compact pagination for Bulma: it returns the html with the series of links to the pages
+    # we use a numeric input tag to set the page and the Pagy.compact javascript to navigate
+    def pagy_nav_compact_bulma(pagy, id=caller(1,1)[0].hash)
+      html, link, p_prev, p_next, p_page, p_pages = +'', pagy_link_proc(pagy), pagy.prev, pagy.next, pagy.page, pagy.pages
+
+      html << %(<nav id="pagy-nav-#{id}" class="pagy-nav-compact-bulma" role="navigation" aria-label="pagination">)
+        html << link.call(MARKER, '', 'style="display: none;"')
+        html << %(<div class="field is-grouped is-grouped-centered" role="group">)
+        html << (p_prev ? %(<p class="control">#{link.call(p_prev, pagy_t('pagy.nav.prev'), 'class="button" aria-label="previous page"')}</p>)
+                        : %(<p class="control"><a class="button" disabled>#{pagy_t('pagy.nav.prev')}</a></p>))
+        input = %(<input class="input" type="number" min="1" max="#{p_pages}" value="#{p_page}" style="padding: 0; text-align: center; width: #{p_pages.to_s.length+1}rem;">)
+        html << %(<div class="pagy-compact-input control level is-mobile">#{pagy_t('pagy.compact.page')}&nbsp;#{input}&nbsp;#{pagy_t('pagy.compact.of')} #{p_pages}</div>)
+        html << (p_next ? %(<p class="control">#{link.call(p_next, pagy_t('pagy.nav.next'), 'class="button" aria-label="next page"')}</p>)
+                        : %(<p class="control"><a class="button" disabled>#{pagy_t('pagy.nav.next')}</a></p>))
+      html << %(</div></nav><script type="application/json" class="pagy-compact-json">["#{id}", "#{MARKER}", "#{p_page}"]</script>)
+    end
+
   end
 end

lib/pagy/extras/responsive.rb

@@ -69,5 +69,24 @@ def pagy_nav_responsive_bootstrap(pagy, id=caller(1,1)[0].hash)
       %(<nav id="pagy-nav-#{id}" class="pagy-nav-responsive-bootstrap pagination" role="navigation" aria-label="pager"><ul class="pagination"></ul></nav>#{script})
     end
 
+    # Responsive pagination for Bulma: it returns the html with the series of links to the pages
+    # rendered by the Pagy.responsive javascript
+    def pagy_nav_responsive_bulma(pagy, id=caller(1,1)[0].hash)
+      tags, link, p_prev, p_next, responsive = {}, pagy_link_proc(pagy), pagy.prev, pagy.next, pagy.responsive
+
+      tags['prev'] = (p_prev ? %(#{link.call(p_prev, pagy_t('pagy.nav.prev'), 'class="pagination-previous" aria-label="previous page"')}<ul class="pagination-list">)
+                             : %(<a class="pagination-previous" disabled>#{pagy_t('pagy.nav.prev')}</a><ul class="pagination-list">))
+      responsive[:items].each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+        tags[item.to_s] = if    item.is_a?(Integer); %(<li>#{link.call item, item, 'class="pagination-link" area-label="goto page '+item.to_s+'"'}</li>)
+                          elsif item.is_a?(String) ; %(<li>#{link.call item, item, 'class="pagination-link is-current" area-current="page" area-label="page '+item.to_s+'"'}</li>)
+                          elsif item == :gap       ; %(<li><span class="pagination-ellipsis">#{pagy_t('pagy.nav.gap')}</span></li>)
+                          end
+      end
+      tags['next'] = (p_next ? %(</ul>#{link.call(p_next, pagy_t('pagy.nav.next'), 'class="pagination-next" aria-label="next page"')})
+                             : %(</ul><a class="pagination-next" disabled>#{pagy_t('pagy.nav.next')}</a>))
+      script = %(<script type="application/json" class="pagy-responsive-json">["#{id}", #{tags.to_json},  #{responsive[:widths].to_json}, #{responsive[:series].to_json}]</script>)
+      %(<nav id="pagy-nav-#{id}" class="pagy-nav-bulma pagination is-centered" role="navigation" aria-label="pagination"></nav>#{script})
+    end
+
   end
 end

lib/pagy/extras/templates/nav_bulma.html.erb

@@ -0,0 +1,24 @@
+<%#
+  This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
+  calls with the actual strings ("&lsaquo; Prev", "Next &rsaquo;", "&hellip;").
+
+  The link variable is set to a proc that returns the link tag.
+  Usage: link.call( page_number [, text [, extra_attributes_string ]])
+-%>
+<% link = pagy_link_proc(pagy) -%>
+<%#                            -%><nav class="pagy-nav-bulma pagination is-centered" role="navigation" aria-label="pagination">
+<% if pagy.prev                -%>  <%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'class="pagination-previous" aria-label="previous page"') %>
+<% else                        -%>  <a class="pagination-previous" disabled><%== pagy_t('pagy.nav.prev') %></a>
+<% end                         -%>
+<% if pagy.next                -%>  <%== link.call(pagy.next, pagy_t('pagy.nav.next'), 'class="pagination-next" aria-label="next page"') %>
+<% else                        -%>  <a class="pagination-next" disabled><%== pagy_t('pagy.nav.next') %></a>
+<% end                         -%>
+<%#                            -%>  <ul class="pagination-list">
+<% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
+<%   if    item.is_a?(Integer) -%>    <li><%== link.call item, item, %(class="pagination-link" area-label="goto page #{item}") %></li>
+<%   elsif item.is_a?(String)  -%>    <li><%== link.call item, item, %(class="pagination-link is-current" area-label="page #{item}" area-current="page") %></li>
+<%   elsif item == :gap        -%>    <li><span class="pagination-ellipsis"><%== pagy_t('pagy.nav.gap') %></span></li>
+<%   end                       -%>
+<% end                         -%>
+<%#                            -%>  </ul>
+<%#                            -%></nav>

lib/pagy/extras/templates/nav_bulma.html.haml

@@ -0,0 +1,32 @@
+-# This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
+-# calls with the actual strings ("‹ Prev", "Next ›", "…").
+
+-# The link variable is set to a proc that returns the link tag.
+-# Usage: link.call( page_number [, text [, extra_attributes_string ]])
+
+- link = pagy_link_proc(pagy)
+
+%nav.pagy-nav-bulma.pagination.is-centered{:role => "navigation", "aria-label" => "pagination"}
+
+  - if pagy.prev
+    != link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'class="pagination-previous" aria-label="previous page"')
+  - else
+    %a.pagination-previous{:disabled => "disabled"}!= pagy_t('pagy.nav.prev')
+
+  - if pagy.next
+    != link.call(pagy.next, pagy_t('pagy.nav.next'), 'class="pagination-next" aria-label="next page"')
+  - else
+    %a.pagination-next{:disabled => "disabled"}!= pagy_t('pagy.nav.next')
+
+  %ul.pagination-list
+
+    - pagy.series.each do |item|                      # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      - if item.is_a?(Integer)                        # page link
+        %li!= link.call item, item, %(class="pagination-link" area-label="goto page #{item}")
+
+      - elsif item.is_a?(String)                      # current page
+        %li!= link.call item, item, %(class="pagination-link is-current" area-label="page #{item}" area-current="page")
+
+      - elsif item == :gap                            # page gap
+        %li
+          %span.pagination-ellipsis!= pagy_t('pagy.nav.gap')

lib/pagy/extras/templates/nav_bulma.html.slim

@@ -0,0 +1,32 @@
+/ This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
+/ calls with the actual strings ("‹ Prev", "Next ›", "…").
+
+/ The link variable is set to a proc that returns the link tag.
+/ Usage: link.call( page_number [, text [, extra_attributes_string ]])
+
+- link = pagy_link_proc(pagy)
+
+nav.pagy-nav-bulma.pagination.is-centered role="navigation" aria-label="pagination"
+
+  - if pagy.prev
+    == link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'class="pagination-previous" aria-label="previous page"')
+  - else
+    a.pagination-previous disabled="disabled" == pagy_t('pagy.nav.prev')
+
+  - if pagy.next
+    == link.call(pagy.next, pagy_t('pagy.nav.next'), 'class="pagination-next" aria-label="next page"')
+  - else
+    a.pagination-next disabled="disabled" == pagy_t('pagy.nav.next')
+
+  ul.pagination-list
+
+    - pagy.series.each do |item|                 # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      - if item.is_a?(Integer)                   # page link
+        li == link.call item, item, %(class="pagination-link" area-label="goto page #{item}")
+
+      - elsif item.is_a?(String)                 # current page
+        li == link.call item, item, %(class="pagination-link is-current" area-label="page #{item}" area-current="page")
+
+      - elsif item == :gap                       # page gap
+        li
+          span.pagination-ellipsis == pagy_t('pagy.nav.gap')