Pager

Easy to use paginator for modern crystal web framework.

Installation

1. Add the dependency to your shard.yml:

dependencies:
  pager:
    github: imdrasil/pager

2. Run shards install

Also if you use default bootstrap presenter ensure that you've added appropriate css to your project from the CDN or directly in the code.

Usage

Pager provides two basic container: for Array and Jennifer::QueryBuilder::ModelQuery. Also it includes basic bootstrap presenter, which is the default presenter.

require "pager"
require "pager/collections/array" # for arrays
require "pager/collections/jennifer" # for Jennifer collections

Collection objects responds to #each method which yield objects in the collection so you can easily iterate over them.

Array

Pager::ArrayCollection extends Array with new #paginate method, which accepts current page and count of elements on each one.

(1..21).to_a.paginate(1, 4) # [5, 6, 7, 8]

Jennifer

Pager::JenniferCollection extends Jennifer::QueryBuilder::ModelQuery with #paginate methods which accepts current page number and count of records in a page. This method is executable one so should be the last one in a chain.

User.all.where { _active }.paginate(1, 4)

Configuration

Pager.configure do |config|
  config.default_presenter = Pager::Bootstrap
  config.visible_pages = 7
  config.per_page = 20
end

Available configurations:

• default_presenter - presenter class to be used by ViewHelper#paginate
• visible_pages - number of page links generated by ViewHelper#paginate
• per_page - default number of pages for collection

View

To render navigation section include Pager::ViewHelper to appropriate context and call #paginate method passing collection, path to be used to generate links and number of visible pages.

<%= paginate((1..100).collection(1, 5), "/", 3) %>

Will generate next html:

<nav>
  <ul class='pagination'>
    <li class="page-item ">
      <a class="page-link" href="/?page=0" aria-label="Previous">
        <span class="sr-only">Previous</span>
        <span aria-hidden="true">&lsaquo; Previous</span>
      </a>
    </li>
    <li class='page-item '>
      <a class='page-link' href='/?page=0'>1</a>
    </li>
    <li class='page-item disabled'>
      <a class='page-link' href='#'>2</a>
    </li>
    <li class='page-item '>
      <a class='page-link' href='/?page=2'>3</a>
    </li>
    <li class="page-item ">
      <a class="page-link" href="/?page=2" aria-label="Next">
        <span class="sr-only">Next</span>
        <span aria-hidden="true">Next &rsaquo;</span>
      </a>
    </li>
  </ul>
</nav>

As you can see page is added as a GET parameter page. If query already has some GET parameter this will be recognized and page will be added to the end.

Translation

The default labels for the "next" and "previous" texts are stored in the i18n yaml. It can be easily override. Here is existing translation file:

pager:
  previous_label: "‹ Previous"
  next_label: "Next ›"

For the translation purpose crimson-knight/i18n.cr library is used.

Development

Presenter

TBA. Take a look at existing bootstrap presenter implementation.

Collection

TBA. Take a look at existing array presenter implementation.

Contributing

1. Fork it (https://github.com/imdrasil/pager/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Roman Kalnytskyi - creator and maintainer