blogc-pagination(7) - blogc's pagination support

blogc-pagination(7)
blogc Manual
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.

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>