1. blogc-pagination(7)
  2. blogc Manual
  3. blogc-pagination(7)

NAME

blogc-pagination - blogc's pagination support

DESCRIPTION

blogc(1) supports some basic pagination and post filtering, when running on listing mode. Files are listed in the order that they are provided to blogc(1) in the command line, no sorting is done.

PAGINATION PARAMETERS

blogc(1) accepts some variables as -D options, that are used to filter the files passed as arguments to it:

FILTER_PAGE

Integer, current page. If calling blogc(1) with 10 files, FILTER_PER_PAGE=4 and FILTER_PAGE=3, it will return just the 2 last files, skipping the first 2 pages with 4 files each one.

FILTER_PER_PAGE

Integer, limits the maximum number of files to be listed. If negative or 0, no posts are included. Have no effect if FILTER_PAGE is not defined.

FILTER_TAG

String, if defined, blogc(1) will only list files that declare a TAGS variable, as a space-separated list of tags (tags can't have spaces, obviously). See blogc-source(7) for details about how to define source variables. The pagination filters will only act on the files with the provided tag, instead of filtering the whole file set.

FILTER_REVERSE

Boolean (1/y/yes/true/on), if set, blogc(1) will list files in reverse order. This filter is combined with FILTER_SORT, and all the other filters will get the files already in the reverse order.

FILTER_SORT

Boolean (1/y/yes/true/on), if set, blogc(1) will sort files using the DATE variable provided in the files, instead of respecting the order of the source files provided to blogc(1). The files are sorted in descending order and combined with FILTER_REVERSE, that will result in the files sorted in ascending order. All the other filters will get the files already sorted.

TEMPLATE VARIABLES

blogc(1) will export some global blogc-template(7) variables, that can be used to build links for next and previous page.

CURRENT_PAGE

Integer, usually the same value of FILTER_PAGE pagination paramenter, if defined, or 1.

FIRST_PAGE

Integer, 1 if more than zero files were listed.

LAST_PAGE

Integer, last page available if more than zero files were listed.

PREVIOUS_PAGE

Integer, CURRENT_PAGE minus 1, if CURRENT_PAGE is bigger than 1.

NEXT_PAGE

Integer, CURRENT_PAGE plus 1, if LAST_PAGE is bigger than CURRENT_PAGE.

blogc(1) can output the value of the variables after evaluation, instead of actually rendering the files, using the -p option. See blogc(1) for details. This is useful to know the last page that needs to be built, using -p LAST_PAGE, for example.

Date variables

blogc(1) will also export some global blogc-template(7) variables related to the DATE variable, as specified in blogc-source(7).

DATE_FIRST
String, DATE variable from the first file in the listing.
DATE_LAST
String, DATE variable from the last file in the listing.

These variables can be also formatted with DATE_FORMAT global blogc(1) parameter, if provided, using DATE_FIRST_FORMATTED and DATE_LAST_FORMATTED global template variables.

File name variables

blogc(1) will also export some global blogc-template(7) variables related to the FILENAME variable, as automatically exported by the source file parser, see blogc-source(7) for details.

FILENAME_FIRST
String, FILENAME variable from the first file in the listing.
FILENAME_LAST
String, FILENAME variable from the last file in the listing.

EXAMPLES

Source file with tags

TITLE: My post
TAGS: foo bar baz
-----------------
Post content

This source file defines 3 tags: foo, bar and baz.

Template with pagination

{% block listing_once %}
<ul class="pager">
    {% ifdef PREVIOUS_PAGE %}
    <li class="previous">
        <a href="/page/{{ PREVIOUS_PAGE }}/">&larr; Newer</a>
    </li>
    {% endif %}
    {% ifdef NEXT_PAGE %}
    <li class="next">
        <a href="/page/{{ NEXT_PAGE }}/">Older &rarr;</a>
    </li>
    {% endif %}
</ul>
{% endblock %}

This example does not uses all the variables, but the concept is the same for all of them.

BUGS

Please report any issues to: https://github.com/blogc/blogc

AUTHOR

Rafael G. Martins <rafael@rafaelmartins.eng.br>

SEE ALSO

blogc(1), blogc-source(7), blogc-template(7)

  1. Rafael G. Martins
  2. May 2019
  3. blogc-pagination(7)