-
Notifications
You must be signed in to change notification settings - Fork 0
/
blogc-pagination.7
133 lines (131 loc) · 4.68 KB
/
blogc-pagination.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "BLOGC\-PAGINATION" "7" "May 2019" "Rafael G. Martins" "blogc Manual"
.
.SH "NAME"
\fBblogc\-pagination\fR \- blogc\'s pagination support
.
.SH "DESCRIPTION"
blogc(1) supports some basic pagination and post filtering, when running on \fBlisting\fR mode\. Files are listed in the order that they are provided to blogc(1) in the command line, no sorting is done\.
.
.SH "PAGINATION PARAMETERS"
blogc(1) accepts some variables as \fB\-D\fR options, that are used to filter the files passed as arguments to it:
.
.TP
\fBFILTER_PAGE\fR
Integer, current page\. If calling blogc(1) with 10 files, \fBFILTER_PER_PAGE=4\fR and \fBFILTER_PAGE=3\fR, it will return just the 2 last files, skipping the first 2 pages with 4 files each one\.
.
.TP
\fBFILTER_PER_PAGE\fR
Integer, limits the maximum number of files to be listed\. If negative or \fB0\fR, no posts are included\. Have no effect if \fBFILTER_PAGE\fR is not defined\.
.
.TP
\fBFILTER_TAG\fR
String, if defined, blogc(1) will only list files that declare a \fBTAGS\fR 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\.
.
.TP
\fBFILTER_REVERSE\fR
Boolean (1/y/yes/true/on), if set, blogc(1) will list files in reverse order\. This filter is combined with \fBFILTER_SORT\fR, and all the other filters will get the files already in the reverse order\.
.
.TP
\fBFILTER_SORT\fR
Boolean (1/y/yes/true/on), if set, blogc(1) will sort files using the \fBDATE\fR 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 \fBFILTER_REVERSE\fR, that will result in the files sorted in ascending order\. All the other filters will get the files already sorted\.
.
.SH "TEMPLATE VARIABLES"
blogc(1) will export some global blogc\-template(7) variables, that can be used to build links for next and previous page\.
.
.TP
\fBCURRENT_PAGE\fR
Integer, usually the same value of \fBFILTER_PAGE\fR pagination paramenter, if defined, or 1\.
.
.TP
\fBFIRST_PAGE\fR
Integer, 1 if more than zero files were listed\.
.
.TP
\fBLAST_PAGE\fR
Integer, last page available if more than zero files were listed\.
.
.TP
\fBPREVIOUS_PAGE\fR
Integer, \fBCURRENT_PAGE\fR minus 1, if \fBCURRENT_PAGE\fR is bigger than 1\.
.
.TP
\fBNEXT_PAGE\fR
Integer, \fBCURRENT_PAGE\fR plus 1, if \fBLAST_PAGE\fR is bigger than \fBCURRENT_PAGE\fR\.
.
.P
blogc(1) can output the value of the variables after evaluation, instead of actually rendering the files, using the \fB\-p\fR option\. See blogc(1) for details\. This is useful to know the last page that needs to be built, using \fB\-p LAST_PAGE\fR, for example\.
.
.SS "Date variables"
blogc(1) will also export some global blogc\-template(7) variables related to the \fBDATE\fR variable, as specified in blogc\-source(7)\.
.
.TP
\fBDATE_FIRST\fR
String, \fBDATE\fR variable from the first file in the listing\.
.
.TP
\fBDATE_LAST\fR
String, \fBDATE\fR variable from the last file in the listing\.
.
.P
These variables can be also formatted with \fBDATE_FORMAT\fR global blogc(1) parameter, if provided, using \fBDATE_FIRST_FORMATTED\fR and \fBDATE_LAST_FORMATTED\fR global template variables\.
.
.SS "File name variables"
blogc(1) will also export some global blogc\-template(7) variables related to the \fBFILENAME\fR variable, as automatically exported by the source file parser, see blogc\-source(7) for details\.
.
.TP
\fBFILENAME_FIRST\fR
String, \fBFILENAME\fR variable from the first file in the listing\.
.
.TP
\fBFILENAME_LAST\fR
String, \fBFILENAME\fR variable from the last file in the listing\.
.
.SH "EXAMPLES"
.
.SS "Source file with tags"
.
.nf
TITLE: My post
TAGS: foo bar baz
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Post content
.
.fi
.
.P
This source file defines 3 tags: \fBfoo\fR, \fBbar\fR and \fBbaz\fR\.
.
.SS "Template with pagination"
.
.nf
{% 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 %}
.
.fi
.
.P
This example does not uses all the variables, but the concept is the same for all of them\.
.
.SH "BUGS"
Please report any issues to: \fIhttps://github\.com/blogc/blogc\fR
.
.SH "AUTHOR"
Rafael G\. Martins <\fIrafael@rafaelmartins\.eng\.br\fR>
.
.SH "SEE ALSO"
blogc(1), blogc\-source(7), blogc\-template(7)