diff options
Diffstat (limited to 'man/blogc-pagination.7.ronn')
| -rw-r--r-- | man/blogc-pagination.7.ronn | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/man/blogc-pagination.7.ronn b/man/blogc-pagination.7.ronn new file mode 100644 index 0000000..db40334 --- /dev/null +++ b/man/blogc-pagination.7.ronn @@ -0,0 +1,122 @@ +blogc-pagination(7) -- 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_PER_PAGE`: + Integer, limits the maximum number of files to be listed. + + * `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_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. + +## 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 }}/">← Newer</a> + </li> + {% endif %} + {% ifdef NEXT_PAGE %} + <li class="next"> + <a href="/page/{{ NEXT_PAGE }}/">Older →</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) |