DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:datatables

DataTables Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Enhance tables with sorting, paging, filtering and more

Last updated on
2023-08-31
Provides
Syntax, Action
Repository
Source
Conflicts with
indexmenu, tabinclude, tablelayout

This plugin implements the DataTables jQuery plugin.

Installation

Search and install the plugin using the 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 defer_js option via Configuration Manager.

Examples/Usage

See the plugin in action here. The sample page shows all the styles available with the plugin.

A simple usage:

<datatables>
^ Column A ^ Column B ^ Column C ^
| Row A1   | Row B1   | Row C1   |
| Row A2   | Row B2   | Row C2   |
| Row A2   | Row B2   | Row C3   |
</datatables>

Some more complex samples

<datatables page-length="50"> [...] </datatables>
<datatables paging="false" ordering="false" info="false" searching="false"> [...] </datatables>

No-Header

<datatables header-rows="true">
| Row A1   | Row B1   | Row C1   |
| Row A2   | Row B2   | Row C2   |
| Row A2   | Row B2   | Row C3   |
</datatables>

Complex Headers

<datatables>
^ Name ^^
^ First ^ Last ^
| My | Name |
| Your | Name |
</datatables>

Syntax

Basic syntax:

<datatables> [...] </datatables>

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

Build Status

Change Log

Bugs / Feature Requests

Please report bugs or feature requests at the Bug tracker.

ToDo/Wish List

FAQ

  • I cannot get the buttons (csv,xls,pdf) to appear as documented: see: discussion on GitHub
  • How to use with the CSV plugin: read the discussion on GitHub1).
  • 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 thread about but don't know if the feature is already implemented in Datatables. Thanks. — Digitalin 2016-02-08 13:16
    • Information is sorted as text by default in Datatables. According to this post and 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) — 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?

This is quite a very nice & practical plugin, that you may use in conjunction with sql plugin, eg:

<datatables page-length="20">
<sql>select * from cms ORDER BY type_id;</sql>
</datatables>

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 ->
<a href="https://forum.dokuwiki.org/forum/28">https://forum.dokuwiki.org/forum/28</a>

but maybe the problem is on sql plugin…

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”):
<sql>
SELECT
 CONCAT('<a href="',table.url,'" target=_blank">',table.url,'</a>') AS url,
...
FROM
    table
...
</sql>

To make “id” in table “table” part of a clickable link:

<sql>
SELECT
 CONCAT('<a href="https://my.website.here/',table.id,'" target=_blank">',table.id,'</a>') AS id,
...
FROM
    table
...
</sql>
<sql>
SELECT
    CONCAT('<a href="https://my.website.here/',table.id,'/details" target="_blank">',table.id,'</a>') AS id,
...
FROM
    table
...
</sql>

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?
1)
fast answer: Include + CSV + DataTables
plugin/datatables.txt · Last modified: 2023-08-31 15:42 by lotar

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki