====== DataTables Plugin ======
---- plugin ----
description: Enhance tables with sorting, paging, filtering and more
author : Giuseppe Di Terlizzi
email : giuseppe.diterlizzi@gmail.com
type : syntax, action
lastupdate : 2023-08-31
compatible : Kaos, Greebo, Frusterick Manners,Elenor of Tsort, Weatherwax, Hrun, Detritus, Hogfather, Igor, "Jack Jackrum"
depends :
conflicts : indexmenu, tabinclude
similar :
tags : datatables, tables, jquery, filter
downloadurl: https://github.com/giterlizzi/dokuwiki-plugin-datatables/zipball/master
bugtracker : https://github.com/giterlizzi/dokuwiki-plugin-datatables/issues
sourcerepo : https://github.com/giterlizzi/dokuwiki-plugin-datatables/
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=9LJDLVSNGYSA2
screenshot_img :
----
This plugin implements the [[https://www.datatables.net/|DataTables]] jQuery plugin.
===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
:!: **Note for Hogfather users** \\
Hogfather use the JS "defer" attribute for speedup the loading of the JS assets, but some users report issues in some plugin and template. If you encounter problems, you can disable [[config:defer_js]] option via Configuration Manager.
===== Examples/Usage =====
See the plugin in action [[http://lotar.altervista.org/dokuwiki/wiki/plugin/datatables|here]]. The sample page shows all the styles available with the plugin.
A simple usage:
^ Column A ^ Column B ^ Column C ^
| Row A1 | Row B1 | Row C1 |
| Row A2 | Row B2 | Row C2 |
| Row A2 | Row B2 | Row C3 |
Some more complex samples
[...]
[...]
==== No-Header ====
| Row A1 | Row B1 | Row C1 |
| Row A2 | Row B2 | Row C2 |
| Row A2 | Row B2 | Row C3 |
==== Complex Headers ====
^ Name ^^
^ First ^ Last ^
| My | Name |
| Your | Name |
===== Syntax =====
Basic syntax:
[...]
==== Options ====
See https://datatables.net/reference/option/ for complete options.
^ Option ^ Description ^ Allowed values ^ Default value ^
| ''auto-width'' | Feature control DataTables' smart column width handling | ''boolean'' | ''true'' |
| ''dom'' | Define the table control elements to appear on the page and in what order | ''string'' | ''lfrtip'' |
| ''info'' | Feature control table information display field | ''boolean'' | ''true'' |
| ''length-change'' | Feature control the end user's ability to change the paging display length of the table | ''boolean'' | ''true'' |
| ''order'' | Initial order (sort) to apply to the table\\ "asc" => ascending, "desc" => descending | ''json array'' | ''%%[[0, "asc"]]%%'' |
| ''ordering'' | Feature control ordering (sorting) abilities in DataTables | ''boolean'' | ''true'' |
| ''page-length'' | Number of elements to display per page | ''integer'' | ''10'' |
| ''paging'' | Enable or disable table pagination | ''boolean'' | ''true'' |
| ''paging-type'' | Pagination button display options | ''simple'' -- 'Previous' and 'Next' buttons only \\ ''simple_numbers'' -- 'Previous' and 'Next' buttons, plus page numbers \\ ''full'' -- 'First', 'Previous', 'Next' and 'Last' buttons \\ ''full_numbers'' -- 'First', 'Previous', 'Next' and 'Last' buttons, plus page numbers | ''simple_numbers'' |
| ''scroll-x'' | Horizontal scrolling | ''px'', ''integer'', ''boolean'' | ''false'' |
| ''scroll-y'' | Vertical scrolling | ''px'', ''integer'', ''boolean'' | ''false'' |
| ''searching'' | Feature control search (filtering) abilities | ''boolean'' | ''true'' |
| ''state-save'' | State saving - restore table state on page reload | ''boolean'' | ''false'' |
Notes:
* The option names are actually used as HTML5 data attributes, so they must be formatted with hyphens-and-lower-case instead of CamelCase (see https://datatables.net/manual/options#HTML-5-data-attributes).
* Do not prepend option names with ''%%data-%%''. The prefix will be added by the plugin.
* Complex option values must be specified using valid JSON, wrapped with single quotes ''%%'%%''. For example: ''%%order='[[0, "asc"]]'%%'', ''%%order='[[0, "desc"]]'%%'' or ''%%search='{"search":"fred"}'%%''.
* Datatables won't work in complex tables, where cells are merged together (e.g. with ":::")
==== Extra Options ====
The plugin also implements extra features beyond the options from DataTables jQuery library.
^ Option ^ Description ^ Allowed values ^ Default value ^
| ''header-rows'' | Makes sure the table header contains at least the specified number of rows, so that it can be formatted by DataTables. It transfers the first rows of the table body into the table header if necessary. Particularly useful when formatting tables generated by other plugins, which may not have created a proper table header. | ''integer'' | ''0'' (no effect) |
===== Extensions =====
^ ^ Attribute ^ Example ^
^ Fixed Header | ''fixed-header'' | ''%%fixed-header="true"%%'' or ''%%fixed-header='{ "header": true, "headerOffset": 50 }' %%'' |
^ Fixed Columns | ''fixed-columns'' | ''%%fixed-columns="true"%%'' |
^ Responsive | ''responsive'' | ''%%responsive="true"%%'' |
^ Buttons | ''buttons'' | ''%%buttons='[ "copy", "csv", "print" ]' %%'' |
===== Configuration and Settings =====
^ Configuration Option ^ Default Value ^ Description ^
| ''excludedPages'' | ''(wiki|playground)'' | Excluded pages (insert a regex) |
| ''enableForAllTables'' | ''0'' | Enable DataTables for all "well formatted" tables |
| ''enableLocalization'' | ''0'' | Enable DataTables localization |
===== Demo =====
The demo and examples is available on [[http://lotar.altervista.org/dokuwiki/wiki/plugin/datatables]].
===== Development =====
[[https://travis-ci.org/LotarProject/dokuwiki-plugin-datatables|{{ https://travis-ci.org/LotarProject/dokuwiki-plugin-datatables.png?nocache|Build Status}}]]
=== Change Log ===
{{rss>https://github.com/LotarProject/dokuwiki-plugin-datatables/commits/master.atom author date}}
=== Bugs / Feature Requests ===
Please report bugs or feature requests at the [[https://github.com/LotarProject/dokuwiki-plugin-datatables/issues|Bug tracker]].
=== ToDo/Wish List ===
===== FAQ =====
* I cannot get the buttons (csv,xls,pdf) to appear as documented: see: [[https://github.com/giterlizzi/dokuwiki-plugin-datatables/issues/54|discussion on GitHub]]
* How to use with the [[CSV]] plugin: read the [[https://github.com/giterlizzi/dokuwiki-plugin-datatables/issues/21|discussion on GitHub]]((fast answer: [[Include]] + [[CSV]] + DataTables)).
* I would like sorting a column by date. dd/mm/yyyy doesn't work. The way I have found is mm.dd which is not obvious (for french people) and Year doesn't match in this format. I follow this [[http://datatables.net/forums/discussion/2467/need-help-for-sorting-date-with-dd-mm-yyyy-format|thread]] about but don't know if the feature is already implemented in [[plugin:datatables|Datatables]]. Thanks. --- [[user>Digitalin|Digitalin]] //2016-02-08 13:16//
* Information is sorted as text by default in Datatables. According to this [[https://datatables.net//forums/discussion/comment/78719/#Comment_78719|post]] and [[https://datatables.net/reference/option/columns.type|documentation]], the best format is yyyy/mm/dd and works well. In case, to get at once a new format with bash : ''sed -E 's,([0-9]{2})/([0-9]{2})/([0-9]{4}),\3\/\2\/\1,g' page.txt > page2.txt'' (to adapt to your situation) --- [[user>Digitalin|Digitalin]] //2016-10-07 14:07//
* It seems the tables default to a background color of white. Is there a way to change that? I tried modifying some values in the plugin css files but they are difficult to read and the changes seemed to have no effect.
* It would be nice if it was possible to state which column the sort should be applied to (as a default)
===== Discussion =====
This plugin looks like the answer to my dreams!:-)
Can it use any of the jQuery DataTables data sources? I.e. can I get data into the table from 'outside'
rather than having to fill the data in the DokuWiki source page? In particular I would like to use the ajax
server side processing to run some PHP to read a database to provide the data.
Also, are the table editing functions of DataTables available?
==== Suggestion: autolink ====
This is quite a very nice & practical plugin, that you may use in conjunction with [[plugin:sql|sql plugin]], eg:
select * from cms ORDER BY type_id;
Only a little suggestion if you use it with sql plugin: wouldn't if be possible to rewrite cells containing an url to a clickable link (like in dw), eg.
https://forum.dokuwiki.org/forum/28 ->
https://forum.dokuwiki.org/forum/28
but maybe the problem is on sql plugin...
=== Possible answer: SQL links ===
One possible answer to the above is to modify the SQL query so it outputs a link.
* To make a URL clickable (where the thing returned from sql is already a URL, in field "''url''"):
SELECT
CONCAT('',table.url,'') AS url,
...
FROM
table
...
To make "''id''" in table "''table''" part of a clickable link:
* To put the id at the end of the link, e.g.: ''https://my.website.here/100''
SELECT
CONCAT('',table.id,'') AS id,
...
FROM
table
...
* To insert the field ''id'' somewhere in the link, e.g.: ''https://my.website.here/100/details''
SELECT
CONCAT('',table.id,'') AS id,
...
FROM
table
...
And other variations on this, for example if you needed multiple fields to build the URL, that's possible too with ''CONCAT''.
Obviously this hack is only useful if you're using datatables with the sql plugin. It also means you can't do "''SELECT *''" because you need to modify the correct field.
I agree that auto-hyperlinks for URLs would be a neat feature. As an aside, the data in the PDF/CSV/Excel export buttons do not contain the URL link but the rendered output, which is probably what you want.
* Any information for Igor support?