Page 6 of 10 | View as a single page

Pagination trails

You use paginator.page_trail to create a pager that will allow your readers to move from page to page. It is set up as follows:

paginate_content:
  trail:
    before: 2
    after: 2

before refers to the number of page links you want to appear before the current page, as much as possible. Similarly, after is the number of page links after the current page. So, in the above example, you have 2 before + 1 current + 2 after = 5 links to pages in your trail “window”.

If you don’t specify the trail properties, or set before and after to 0, all page links will be returned.

Let’s say your document has 7 pages, and you have a trail as above. The pager would look something like this as you go from page to page:

« <1> [2] [3] [4] [5] »
« [1] <2> [3] [4] [5] »
« [1] [2] <3> [4] [5] »
« [2] [3] <4> [5] [6] »
« [3] [4] <5> [6] [7] »
« [3] [4] [5] <6> [7] »
« [3] [4] [5] [6] <7> »

Usage

paginator.page_trail has the following fields:

Field Description
num The page number
path The path to the page
title The title of the page

Here is an example adapted from JPv2’s documentation. Note that you don’t need to prepend site.baseurl to trail.path as it is automatically added in by JPC by default.

{% if paginator.page_trail %}
  <ul class="pager">
  {% for trail in paginator.page_trail %}
    <li {% if page.url == trail.path %}class="selected"{% endif %}>
        <a href="{{ trail.path }}" title="{{ trail.title }}">{{ trail.num }}</a>
    </li>
  {% endfor %}
  </ul>
{% endif %}

Its accompanying style:

<style>
  ul.pager { text-align: center; list-style: none; }
  ul.pager li {display: inline;border: 1px solid black; padding: 10px; margin: 5px;}
  .selected { background-color: magenta; }
</style>

You’ll end up with something like this, for page 4:

The author’s own pager is a little more involved and uses some convenience fields and aliases:

{% if paginator.page_trail %}
  <div class="pager">
    {% if paginator.is_first %}
      <span class="pager-inactive"><i class="fa fa-fast-backward" aria-hidden="true"></i></span>
      <span class="pager-inactive"><i class="fa fa-backward" aria-hidden="true"></i></span>
    {% else %}
      <a href="{{ paginator.first_path }}"><i class="fa fa-fast-backward" aria-hidden="true"></i></a>
      <a href="{{ paginator.previous_path }}"><i class="fa fa-backward" aria-hidden="true"></i></a>
    {% endif %} 

    {% for p in paginator.page_trail %}
      {% if p.num == paginator.page %}
        {{ p.num }} 
      {% else %}
        <a href="{{ p.path }}" data-toggle="tooltip" data-placement="top" title="{{ p.title }}">{{ p.num }}</a>
      {% endif %}
    {% endfor %}

    {% if paginator.is_last %}
      <span class="pager-inactive"><i class="fa fa-forward" aria-hidden="true"></i></span>
      <span class="pager-inactive"><i class="fa fa-fast-forward" aria-hidden="true"></i></span>
    {% else %}
      <a href="{{ paginator.next_path }}"><i class="fa fa-forward" aria-hidden="true"></i></a>
      <a href="{{ paginator.last_path }}"><i class="fa fa-fast-forward" aria-hidden="true"></i></a>
    {% endif %} 
  </div>
{% endif %}

This results in a pager that looks like this:

Page flipper

You may also want to add a page “flipper” that uses section names:

<!--page_footer-->
<div>
  {% if paginator.previous_section %}
    &laquo; <a href="{{ paginator.previous_path }}">{{ paginator.previous_section }}</a>
  {% endif %}
  {% if paginator.previous_section and paginator.next_section %} | {% endif %}
  {% if paginator.next_section %}
    <a href="{{ paginator.next_path }}">{{ paginator.next_section }}</a> &raquo;
  {% endif %}
</div>

Should there be no available section name, “Untitled” will be returned. You can then handle it like so:

{% if paginator.previous_section == "Untitled" %}
  Previous
{% else %}
  {{ paginator.previous_section }}
{% endif %}

Of course, you always have the option of adding some navigational cues to your content:

{% if paginator.paginated %}
  <a href="{{ paginator.next_page_path }}">On to the next chapter...</a>
{% endif %}

This text will not appear in the single-page view.

4 5 6 7 8