-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
352 lines (298 loc) · 21.5 KB
/
README.html
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="utf-8"/>
</head>
<body>
<h1 id="tablesorter-pagercontrols">tablesorter-pagercontrols</h1>
<p>This jQuery plug-in is an add-on for <a href="https://github.com/Mottie/tablesorter">mottie’s tablesorter plug-in</a>, more explicitly its pager add-on. It programmatically adds pager controls below a table and applies the pager add-on for large HTML tables, so that you don’t have to insert the controls to the HTML manually any more.</p>
<p><a href="https://www.isg-software.de/tspagercontrols/indexe.html">Project Home Page</a></p>
<h2 id="whatsnew">What’s new?</h2>
<p>V1.6 (Sept. 2023):</p>
<ul>
<li>introduced Aria-Labels to the pager buttons for better accessibility,</li>
<li>introduced new option <code>buttonLabelClass</code>,</li>
<li>added new classes <code>flipLeft</code> and <code>rotateLeft</code> to default CSS which both can be used as values for the new <code>buttonLabelClass</code> option if the button label for the left buttons (first and prev) are in fact right-pointing arrows of some kind,</li>
<li>updated the template <code>triangleIcons</code> to use the same right-pointing arrow icon for all button labels and flip the left buttons using the aforementioned options and class.</li>
</ul>
<p>V1.5 (Sept. 2023): Introduced the additional options <code>forcePager</code> and <code>pagerOptions</code>, see default options below. These were mainly added in order to support Ajax-based Pagers.</p>
<h2 id="motivation">Motivation</h2>
<p>The “normal” usage of the tablesorter’s pager add-on requires you to manually create a user interface (control buttons to skip pages, page size selection and page display) in your HTML document (in addition to the table). The following HTML fragment is taken from an original example page:</p>
<pre><code class="html"><table class="tablesorter">
<!-- view page source to see the entire table -->
</table>
<!-- pager -->
<div id="pager" class="pager">
<form>
<img src="first.png" class="first"/>
<img src="prev.png" class="prev"/>
<!-- the "pagedisplay" can be any element, including an input -->
<span class="pagedisplay" data-pager-output-filtered="{startRow:input} &ndash; {endRow} / {filteredRows} of {totalRows} total rows"></span>
<img src="next.png" class="next"/>
<img src="last.png" class="last"/>
<select class="pagesize">
<option value="10">10</option>
<option value="20">20</option>
<option value="30">30</option>
<option value="40">40</option>
<option value="all">All Rows</option>
</select>
</form>
</div>
</code></pre>
<p>When calling the <code>tablesorterPager</code> plug-in, you may then “connect” these controls with the pager by setting corresponding options to the classes of the controls. This way, the plug-in is “wired” to your controls and adds the application logic to your UI.</p>
<p>While that is a clear separation of logic (in javascript) and user interface (in HTML) and offers you great freedom of UI design, I personally was looking for a solution which (just like the main <code>tablesorter</code> functionality) is directly applicable to any table in my web application’s output without requiring the web app itself to include controls into its output.</p>
<p>So, the goal of <em>this</em> plug-in is to get rid of pager-specific HTML mark-up in the document. If you, too, want to dynamically apply a table sorter and pager to one or more tables inside some HTML document via JavaScript, while the HTML really only holds the data table, have a look at this plug-in.</p>
<p>Instead of manually adding controls like those shown above to your HTML document and calling the <code>tablesorterPager</code> plug-in, you simply call this <code>appendTablesorterPagerControls</code> plug-in on your jQuery resultset. It automatically appends a <code>div</code> element beneath the table holding the default controls and then internally applies the <code>tablesorterPager</code>, ‘wiring’ it to the inserted controls.</p>
<h2 id="features">Features</h2>
<ul>
<li>Checks whether the table is larger than the smallest page size option. Only adds the pager if that’s the case, i.e. non-pageable tables will not be equipped with a useless pager.
<ul>
<li>This can now be overruled by the option <code>forcePager: true</code>, if you want to insert the pager regardless of the table size. This is especially useful if you insert an empty table and want it to be filled by partial data via Ajax requests (which is am optional feature of the Tablesorter Pager Plug-in).</li>
</ul></li>
<li>In difference to the typical examples like the source code shown above, this plug-in does not insert images but real HTML 5 buttons (<code><button>…</button></code> elements).
<ul>
<li>By default these look like any button of the user’s OS, but the buttons can also be styled. This plug-in contains a <code>pillbuttons.css</code> stylesheet demonstrating styling capabilities by creating flat buttons with hover effect shaped with semicircles on the left- and righthand side.</li>
<li>Unavailable buttons (previous/first page buttons on page one or next/last page buttons on the last page) get disabled.</li>
</ul></li>
<li>Button labels are configurable via options.</li>
<li>All controls support tooltips (via the <code>title</code> attribute).
<ul>
<li>Default tooltips are available in english or german.</li>
<li>On source level, tooltips are defined in separate scripts files for easy localization.</li>
<li>Tooltips may also be overridden locally via the plug-in options.</li>
</ul></li>
<li>More options include selectable page sizes, initial page size and CSS class names for the generated HTML elements.</li>
<li>The page display element may be <em>either</em>
<ul>
<li>a disabled text input element (sporting fixed width and the standard form font also used for the button labels and page size select box) <em>or</em></li>
<li>normal document text.
<ul>
<li>Only in this case, the following pager plug-in’s optional feature is available: The current page number and/or current number of the first line may be inserted as input fields. The user can then enter a number and press return in order to directly switch to the desired page (resp. page holding the desired line).</li>
</ul></li>
</ul></li>
</ul>
<h2 id="dependencies">Dependencies</h2>
<ul>
<li>Needs <a href="https://www.npmjs.com/package/tablesorter">tablesorter</a>. Tested with 2.28.4, and requires at least this version for the option <code>outputFiltered</code> to work. If you don’t use the filter widget or you don’t need a different page display for filtered tables, this should also be compatible with earlier versions of tablesorter.</li>
<li>Needs <a href="https://www.npmjs.com/package/jquery">jQuery</a>. Tested with jQuery 3 (the NPM module definces a dependency to jquery V3.x.x), but should also be compatible with some earlier versions.</li>
</ul>
<h2 id="usage">Usage</h2>
<p>Include the script files for jQuery, tablesorter, the pager and this plug-in to your HTML as well as the desired CSS files (you may use the bundled style sheets or create your own).</p>
<p>Select your tables via jQuery and apply the <code>tablesorter</code> and <code>appendTablesorterPagerControls</code> (instead of <code>tablesorterPager</code>) to the result set.</p>
<p>Your HTML’s head might look like this:</p>
<pre><code class="html"><!DOCTYPE html>
<html>
<head>
<title>…</title>
<meta charset="utf-8">
<link rel="stylesheet" href="node_modules/tablesorter/dist/css/theme.blue.css" type="text/css">
<script type="text/javascript" src="node_modules/jquery/dist/jquery.js"></script>
<script type="text/javascript" src="node_modules/tablesorter/dist/js/jquery.tablesorter.min.js"></script>
<script type="text/javascript" src="node_modules/tablesorter/dist/js/extras/jquery.tablesorter.pager.min.js"></script>
<script type="text/javascript" src="js/jquery.tablesorter.pager.appendcontrols.english.min.js"></script>
<link rel="stylesheet" href="css/jquery.tablesorter.pager.appendcontrols.css" type="text/css">
<script type="text/javascript">
$(function() {
$("table")
.tablesorter({widthFixed: true, widgets: ['zebra']})
.appendTablesorterPagerControls();
});
</script>
</head>
</code></pre>
<p>The minified (distribution) script files include the main plug-in code as well as the tooltip definitions in one language. Therefore you’ll find the script file in different versions, named after the tooltip language.</p>
<p>If you want to include the unminified source scripts (e.g. for debugging purposes or if you’ve created a new language file and not yet compiled a new distribution file using it), you’ll have to first load the main script file (<code>jquery.tablesorter.pager.appendcontrols.js</code>) followed by the various other files like <code>defaults.js</code> and lastly the language pack file (e.g. <code>jquery.tablesorter.pager.appendcontrols.english.js</code>).</p>
<p>The <code>appendTablesorterPagerControls()</code> method optionally takes one or more objects as arguments which each may override default options. This means:</p>
<ul>
<li>Calling the function without arguments applies the default options,</li>
<li>calling the function with one argument, this has to be an option containing all those options which you want to differ from the defaults.</li>
<li>If you call the function with more than one argument (e.g. one object with user-defined options and one or more so-called templates, globally defined option sets overriding some specific options), all these options objects will be merged into a copy of the defaults. I.e. the options in the first argument override defaults, options in the second argument may override options of the first argument and so on.</li>
</ul>
<p>The default options are defined as follows (and may also be globally overwritten):</p>
<pre><code class="javascript">$.fn.appendTablesorterPagerControls.defaults = {
/**
* The table sizes (number of visible rows) selectable by the user.
* Array of numbers, must be sorted (ascending) and not empty.
*/
sizes: [20, 30, 40, 50, 100],
/**
* Initial table size.
* This must be a single element (number) of the sizes array to be preselected
* when loading the page / applying the plug-ing.
*/
initialSize: 20,
/**
* Prefix string used for generated element IDs.
* The ID for the DIV element holding the pager controls will consist of this prefix plus a number.
* Form elements within that DIV will get an ID starting identically, but with a further suffix:
* "sel" for the table size select box and "pgnr" for the input with the page number display.
*/
prefix: "tableSorterPager",
/**
* Pattern for the arrangement of the control elements.
* {first}, {prev}, {next}, and {last} are placeholders for the navigation buttons,
* {size} will be replaced with the select box for selecting the number of visible rows,
* {display} stands for the status display as formatted with the output option.
*/
controlsOutput: '{first}{prev}{display}{next}{last}{size}',
/**
* This output option is passed directly to the tablesorter pager plug-in.
* Defines the pattern of information to be displayed in the page display.
* (For details see the pager documentation.)
* Please note, that if you change this pattern, it's recommended to also change the
* corresponding tooltip text (see language-specific files).
*/
output: '{page}/{totalPages} ({startRow}-{endRow}/{totalRows})',
/**
* second output pattern only used when the 'filter' widget is applied to the table and the user
* entered a filter, i.e. the table does not show all rows.
* If null, the output pattern will not change for filtered tables. But you may use this option
* to define a separate output pattern containing the {filteredRows} or {filteredPages} placeholders.
*/
outputFiltered: null,
/**
* Size (width) for the input holding the page display. You may change this option
* corresponding to the output option.
* Or set to 0 or null in order to disable the input field completely and render the display
* as styleable text (in a span field).
*/
pagedisplayInputSize: null,
/**
* CSS class for the 'next page' button, defaults to 'next'.
*/
classNext: "next",
/**
* CSS class for the 'previous page' button, defaults to 'prev'.
*/
classPrev: "prev",
/**
* CSS class for the 'first page' button, defaults to 'first'.
*/
classFirst: "first",
/**
* CSS class for the 'last page' button, defaults to 'last'.
*/
classLast: "last",
/**
* CSS class for the span or input for displaying the current page, page count etc. (see output option for formatting this display).
* Defaults to 'pagedisplay'.
* NOTE: If you change this value, the included CSS files will not work completely, but will have to be adapted to the new class name.
*/
classPagedisplay: "pagedisplay",
/**
* CSS class for the page size selection (select element, defaults to 'pagesize').
*/
classPagesize: "pagesize",
/**
* CSS class for a div element wrapped around the table and its pager controls.
* Defaults to 'tablesorterPagerWrapper'.
* May also be space-separated list of class names like in any class attribute of an HTML element.
*/
classWrapper: "tablesorterPagerWrapper",
/**
* CSS class for a div element wrapped around the table and its pager controls within the
* wrapper of class 'classWrapper'. Defaults to null, in which case no inner wrapper is added.
* If non-null, the table and its conrols will be wrapped doubly like:
* <div class='classWrapper'><div class='classInnerWrapper'><table>...</table><div class='classControls'>...</div></div></div>.
* By default, this inner div won't be added, but it can be used for some CSS tricks: So the outer wrapper
* may be displayed as a block while the inner's display style may be set to 'inline-block' which
* allows for example to align the controls to the right with the table even if the table is not full-width.
* May also be space-separated list of class names like in any class attribute of an HTML element.
*/
classInnerWrapper: null,
/**
* CSS class for a div element wrapped around the table only (inside the optional innerWrapper).
* Defaults to null, in which case no such table wrapper is added.
* If non-null, the table will be wrapped like this:
* <div class='classWrapper'><div class='classTableWrapper'><table>...</table></div><div class='classControls'>...</div></div>.
* Or, if the classInnerWrapper is also non-null:
* <div class='classWrapper'><div class='classInnerWrapper'><div class='classTableWrapper'><table>...</table></div><div class='classControls'>...</div></div></div>.
* So, by default this table wrapper won't be added, but it may be added for some CSS formatting.
* It's especially useful if you may have very wide table and want them to be horizontally scrollable.
* In this case, you may set this option and introduce a CSS rule setting overflow-x: scroll for the table wrapper.
* That way, the table itself will be scrollable (if wider that the viewport) while the table pager controls beneath
* it (as well as content above the table or beneath the pager controls) will stay fixed and won't scroll left or right
* with the table, i.e. the user will always see and will always be able to operate the pager regardless of
* the horizontal scroll position of the table.
*/
classTableWrapper: null,
/**
* CSS class for a div element containing the table pager controls (inserted below the table).
* Defaults to 'tablesorterPagerControls'.
* NOTE: If you change this value, the included CSS files will not work completely, but will have to be adapted to the new class name.
*/
classControls: "tablesorterPagerControls",
/**
* button label for the 'first page' button.
*/
labelFirst: "&lt;&lt;",
/**
* button label for the 'previous page' button.
*/
labelPrev: "&lt;",
/**
* button label for the 'next page' button.
*/
labelNext: "&gt;",
/**
* button label for the 'last page' button.
*/
labelLast: "&gt;&gt;",
/**
* If this is a string, each button label will be wrapped in a span with a class attribute, and this property defines
* the latter's value.
* This may e.g. be used to add the class "flipLeft" to each button label. The default CSS will then horizontally flip
* these button labels for the left two buttons (prev and first).
* Alternatively, you may use the class "rotateLeft", which will by default rotate the button labels of the prev- and first-
* buttons by 180 degrees.
*/
buttonLabelClass: null,
/**
* If false, pager buttons are only added to a table if that table contains more rows than
* the smallest page size (i.e. actual row count < sizes[0]).
* Set this to true to force appending pager controls regardless of actual table size (e.g. if the
* table is still empty and will be populated via ajax requests).
*/
forcePager: false,
/**
* Any properties of this object will be passed directly to the original tablesorterPager plugin.
* This is empty by default, as usually all needed pager options are automatically generated by this plug-in.
* May be used, e.g., to add ajax options (ajaxUrl, ajaxProcessing, etc.).
*/
pagerOptions: {}
};
</code></pre>
<p><a href="src/js/defaults.js">defaults.js</a></p>
<p>As you can see in the example call above, you don’t apply the tablesorter’s pager plug-in directly, but you only apply the <code>tablesorter()</code> plug-in method, followed directly by the <code>appendTablesorterPagerControls()</code> call. The latter will apply the <code>tablesorterPager()</code>-call automatically for you. The options to this <code>tablesorterPager()</code> are calculated by this plug-in.</p>
<p>There might be situations where you want to specify your own options to pass to <code>tablesorterPager()</code>, like e.g. several of the <code>ajax*</code> properties which enable getting pages of table rows via Ajax calls from a server. You can now do so by collecting these in the <code>pagerOptions</code> property. Such a call would thus look something like this:</p>
<pre><code class="javascript">$("table")
.tablesorter({
… options for tablesorter …
})
.appendTablesorterPagerControls({
… options for appendTablesorterPagerControls …
pagerOptions: {
… additional options for tablesorterPager …
(besides those automatically calculated)
}
});
</code></pre>
<h3 id="templates">Templates</h3>
<p>As said, you may call the jQuery plug-in with an object as argument holding those options you wish to override. If you want to repeatedly override a whole subset of options, you may aggregate these into template objects.
Four predefined templates are included, see <a href="src/js/templates.js">templates.js</a>.</p>
<p>The application of these templates is demonstrated in the examples.</p>
<h2 id="examples">Examples</h2>
<p>If you download the package from GitHub or NPM, you’ll find it includes some example pages.</p>
<p>Online views of these examples can also be found on the <a href="https://www.isg-software.de/tspagercontrols/indexe.html">project’s home page</a>.</p>
<h2 id="license:bsd2-clause">License: BSD 2-clause</h2>
<p>Copyright (c) 2023, Immo Schulz-Gerlach, www.isg-software.de<br />
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<ol>
<li><p>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</p></li>
<li><p>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</p></li>
</ol>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</body>
</html>