Unmaintained

This gem is no longer maintained and I have no plans to update it.

Middleman Pagination

General-purpose pagination support for Middleman.

Middleman resources, proxy pages, and any arbitrary collection of objects can be paginated.

Installation

Add this line to your Middleman site's Gemfile:

gem 'middleman-pagination'

And then execute:

$ bundle

Or install it yourself as:

$ gem install middleman-pagination

Usage

Let's say you have a set of recipes that you want to create pagination for:

source/
    all-recipes.html
    recipes/
        apple-pie.html
        bacon.html
        cake.html

Inside your config.rb:

activate :pagination do
  pageable_resource :recipes do |page|
    # Match any page that lives in the "recipes" directory
    page.path.start_with?('recipes/')
  end
end

Note: If you're using the directory indexes extension, place it after activate :directory_indexes.

Now, let's set up a pagination index. Inside all-recipes.html:

---
pagination:
  for: recipes
  per_page: 20
---

<% pagination.each do |recipe| %>
  - <%= link_to recipe.data.title, recipe.url %>
<% end %>

Page <%= pagination.page_num %> of <%= pagination.total_page_num %>

Showing <%= pagination.per_page %> per page

<%= link_to "First page", pagination.first_page.url %>

<%= link_to "Prev page", pagination.prev_page.url if pagination.prev_page %>

<%= link_to "Next page", pagination.next_page.url if pagination.next_page %>

<%= link_to "Last page", pagination.first_page.url %>

Note: the for and per_page properties must be indented for the pagination frontmatter (per_page is optional).

You can define as many different types of pageable resources as you like, with whatever criteria you like:

activate :pagination do
  pageable_resource :staff do |page|
    # Match any page whose URL includes "/staff/"
    page.url.include?('/staff/')
  end

  pageable_resource :news do |page|
    # Match any page that has a "news" property in its frontmatter
    page.data.news.present?
  end
end

Custom path

If your pagination index is called all-recipes.html, the subsequent pages will ba named all-recipes/pages/2.html, all-recipes/pages/3.html, and so on.

You can customise the path with the path pagination frontmatter. For example, in all-recipes.html:

---
pagination:
  for: recipes
  path: p/:num
---

Your pages would be created at all-recipes/p/2.html, all-recipes/p/3.html, etc.

Paginate data

You aren't limited to just pages. You can paginate over Middleman Local Data, too.

Let's say you had a file called roman_gods.yml in your data directory:

- name: Jupiter
  title: King of the Gods
- name: Juno
  title: Queen of the Gods
- name: Neptune
  title: God of the Sea
- name: Pluto
  title: God of Death

...snip...

You can produce pagination by using pageable_set:

activate :pagination do
  pageable_set :gods do
    data.roman_gods
  end
end

In your template:

---
pagination:
  for: gods
  per_page: 10
---

<% pagination.each do |god| %>
  - <%= god.name %> (<%= god.title %>)
<% end %>

<%= link_to "Next page", pagination.next_page.url if pagination.next_page %>

Paginate anything

In fact, you can paginate any collection of objects that responds to each, by using pageable_set:

activate :pagination do
  pageable_set :planets do
    ['Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune']
  end
end

The set can be used in exactly the same way:

---
pagination:
  for: planets
  per_page: 4
---

Planets (showing <%= pagination.per_page %> per page):

<% pagination.each do |planet| %>
  - <%= planet %>
<% end %>

<%= link_to "Next page", pagination.next_page.url if pagination.next_page %>

Getting help

Bug? Feature request? You can open an issue, contact me on Twitter, or start a new topic on the Middleman forums. All feedback and suggestions welcome.

TODO

Custom sorting (e.g. by date)
Add tests for metadata support
Convenience helper methods (e.g. make pagination. optional)
Pagination link generator (e.g. Pages: 1 2 [3] ... 7 8 9)
Adopt Middleman's Queryable interface (potentially requires changes to Middleman first)

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

Aupajo/middleman-pagination

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Error
Looks like something went wrong!

Packages