JQDataTablesPlugin

JQuery based progressive enhancement of tables

Overview

This plugin implements a widget to enhance normal HTML tables with extra navigation features such as sorting, filtering and paginating through datasets. The %DATATABLE macro is specifically tailored towards datasets created on the base of DataForms. It lets you easily compile an overview of data of that kind stored in a web as well as select specific records for further use in wiki apps.

JQDataTablesPlugin can be used in two distinct ways:

• by means of the %DATATABLE macro
• by means of HTML5 and JSON to enhance HTML tables directly

%DATATABLE takes a pointer to a DataForm definition and then creates a table based on the known formfields in that definition to create columns of a kind matching the formfield types. It then uses a connector fetch the data from the backend. There are several kinds of connectors available at the moment based on the additional functionality installed on your Foswiki:

• search: this one uses the normal native search feature of Foswiki also used by the %SEARCH macro
• dbcache: this one uses DBCachePlugin which is implementing a faster still native search, also available via its %DBQUERY macro
• solr: this connector uses the SolrPlugin which uses a Solr fulltext search engine integrated into Foswiki.

A default connector can be defined as required. Note however, that even though %DATATABLE tries to hide the differences of available connectors behind the scene, connectors will behave differently, i.e. when it comes to filtering. Also, performance is vastly different with the search connector being the slowest one. It is strongly recommended that you at least install DBCachePlugin for acceptable performance in every-day usage.

DATATABLE

Using a %DATATABLE you can query a set of topics and display their structured data in a dynamic table. Results are best when querying structured data attached to your topics as each formfield defined in the DataForm directly correlates to a column in the generated table. In this case you may specify the form definition in the form parameter and formfields in the columns parameter. The %DATATABLE will then use this information to properly display formfield values as well as sort columns along the technical representation. For example a date formfield will properly be displayed according to your locale's date format while sorting by date uses date values represented as epoch seconds.

Syntax: %DATATABLE{"<query>" parameter="..." parameter="..." ...}%

Parameter	Description	Default
<query>, query	specify a search query to filter rows on the server-side; NOTE: the query language might vary depending on the connector being used, e.g. dbcache vs search vs solr
connector	connector to be used to fetch data dynamically from the backend; possible values are search (using Foswiki's native %SEARCH), dbcache (needs Foswiki:Extensions/DBCachePlugin), solr (needs Foswiki:Extensions/SolrPlugin), additional connectors may be implemented by plugins; NOTE: for general-purpose search dbcache is the best choice	defined in $Foswiki::cfg{JQDataTablesPlugin}{DefaultConnector}
class	additional css class to be added to the widget in addition to foswikiTable
width	width of table, e.g. 100% and the like
web, webs	web or list of webs to query for data	current web
topics	list of topics to query per web
include	regular expression topics must match to be included
exclude	regular expression topics must not match to be included
form	data form definition
buttons	list of buttons to add; available buttons are: print, csv, excel, copy, pdf
paging, pager	switch on/off paging data; NOTE: this parameter is deactivated when scrolling is specifed as well (see docu)	off
pagelength, rows	number of rows to be displayed when paging is enabled (see docu)	10
lengthmenu	switches on a menu element to change the page length (see docu)	10, 25, 50, 100
scrolling, scroller	switch on/off dynamic scrolling; data will be fetched from the backend as you are scrolling up and down; NOTE: this parameter disables paging as these two features are mutual exclusive	off
searching	switch on/off the global search box (see docu)	off
searchmode	defines how to search, either using one search box covering all columns (global), or using one search box per column (multi)	global
searchdelay	delay before changes in a search box will cause new data to be fetched from the backend	400
sort	specifies the column for initial ordering; note that sorting is performed on the server side by default	first column
reverse	specifies the initial ordering direction	off
savestate	switch on/off remembering the state the datatable was in when coming back to the page; this includes sorting, paging as well as filtering; state information is stored in the browser's session store, that is state information is specific to the browser tab; closing a browser tab will purge all state infos of datatables with it	off
info	switch on/off the info about the number of rows in the set (see docu)	off
ordering	switch on/off the ability to sort the table by clicking on a column header (see docu)	on
scrollx	switch on/off horizontal scrolling (see docu)	off
scrolly	specify vertical scrolling (see docu)	off
scrollcollapse	switch on/off collapsing of the table height on small data sets (see docu)	off
columns	comma-separated list of formfield names to be displayed; see the notes on special columns below	all formfields of the DataForm specified by form
rowgroup	comma-separated list of columns that should be used to create groups of rows
selecting	switch on/off select extension
selectproperty	specifies the property of a row to be selected when selection is enabled	topic
selectname	specifies the name of the data be submitted when selection is enabled	<selectproperty>
selectmode	possible values are os, single, multi, this specifies the way a selection is made (see docu)	multi
responsive	switch on/off responsive extension
fixedheader	switch on/off fixed header extension
hidecolumns	comma-separated list of columns to hide from the output; while hidden column data is still fetched available for further processing such as grouping or styling a row
rowclass	javascript function that is supposed to return a css class when a row is rendered; the string returned is added as a class to the row elements of the table
rowcss	javascript function that is supposed to return a string or an object to apply inline css to all cells of a row
autocolor	comma-separted list of columns to auto-color based on the cell content; note this needs the JQAutoColorContrib to be installed and activated
datetimeformat	date format to be recognized by the frontend
<field-name>_title	a column title for a given field-name, e.g. ProjectState_title="Status"	name of the formfield as specified in columns
<field-name>_width	column width for a given field, e.g. ProjectID_width=5em

DATATABLESECTION, ENDDATATABLESECTION

This makro can be used to start wrapping HTML tables inside a dedicated section to augment them in functionality.

Syntax:

%DATATABLESECTION{<parameters>}% 

... one or more HTML tables ... 

%ENDDATATABLESECTION%

All HTML tables inside a datatables section will be assigned the same set of parameters. All of the parameters of a regular %DATATABLE can be used as defined above except columns, query and connector. Instead of fetching data from the backend using ajax data is embeded as a HTML table inside the page. No backend interaction will take place other than the initial HTML page embeding all data beforehand.

Special column names

In general column names specified in the columns parameter of the %DATATABLE parameter directly relate to a formfield of an attached DataForm. Values are displayed and sorted according the the type of the formfield. There are however a few column names that have a special meaning or trigger an additional behavior on data in this column:

• index: this is an auto-generated column enumerating the rows in a table
• Date, Changed, Modified, Created, info.date, createdate: these fields are all date fields and treated accordingly
• Topic: alias for topic
• TopicTitle: displays the TopicTitle of a topic linking to it
• By: alias for author of recent topic revision
• Creator, createauthor, info.author: author if the initial topic revision
• publishauthor: author that published the topic, defaults to createauthor in case there is no explicit Author field in the form
• publishdate: date when the publishauthor created the initial revision, defaults to createdate in case there is no explicut PublishDate field in the form
• worflow: name of the workflow assigned to a topic
• QMPlugin fields:
  • qmstate: title of the current workflow state
  • qmstate_id: id of the current workflow state
  • qmstate_pendingReviewers: list of users that still need to action on a state change in a parralel transition
  • qmstate_possibleReviewers: list of users that might change the current state
  • qmstate_pendingApprover: list of users that might transition the current state to the "approved" state
  • qmstate_reviewers: list of users that reviewed the current state
  • qmstate_comments: coments of all reviews of the current state
• access control settings of the current topic
  • allowchange
  • allowview
  • allowapprove
  • allowcomment
  • allowcreate
  • denychange
  • denyview
  • denyapprove
  • denycomment
  • denycreate
• MetaDataCommentPlugin fields:
  • comments: number of comments of the current topic

Examples

DATATABLESECTION simple example

%STARTSECTION{"example0"}%
%DATATABLESECTION%
| *Header* | *Header* | *Header* | *Header* |
| Data | Data | Data | Data |
| Data | Data | Data | Data |
| Data | Data | Data | Data |
| Data | Data | Data | Data |
%ENDDATATABLESECTION%
%ENDSECTION{"example0"}%

DATATABLESECTION with formatted search

This example generates a table dynamically using a FormattedSearch:

%STARTSECTION{"example1"}%
%DATATABLESECTION{paging="on" searching="on" info="on"}%
%SEARCH{
  "1"
  type="query"
  topic="*Plugin"
  header="| *Name* | *Date* | *Author* |"
  format="| $topic | $date | $wikiusername |"
  nonoise="on"
}%
%ENDDATATABLESECTION%
%ENDSECTION{"example1"}%

Client side sorting

JQDataTablesPlugin comes with additional sorting features for specific types of data:

• numeric
• string
• date (extended to be able to parse Foswiki's default date format)
• currency
• metrics (e.g. killo, mega, giga, tera, …)

Click on the table headers to sort the columns according to their data type.

%STARTSECTION{"example2"}%
%DATATABLESECTION%
| *#* | *String* | *Date* | *Number* | *Currency* | *Size* |
| 3 | ActionTrackerPlugin | 27 Jan 2010 - 17:07 | 1 | 1,00 | 10KB |
| 1 | AntiWikiSpamPlugin | 03 Jan 2013 - 09:07 | 10 | 10,00 | 3GB |
| 2 | RenderListPlugin | 13 May 2012 - 02:59 | 0.01 | 1,01 | 100MB |
| 5 | CommentPlugin | 10 Apr 2011 - 23:39 | 100 | 0,10 | 2024kB |
| 4 | FindElsewherePlugin | 23 Dec 2012 - 17:06 | 20 | 100,- | 0.1kB |
| 6 | JsonRpcContrib |  | 0 | -100,- | 1024TB |
%ENDDATATABLESECTION%
%ENDSECTION{"example2"}%

List of PackageForm topics

Below example lists all topics in the System web that have the PackageForm attached to it:

%STARTSECTION{"example3"}%
%DATATABLE{
   web="%SYSTEMWEB%"
   form="%SYSTEMWEB%.PackageForm"
   paging="on"
   searching="on"
   info="on"
   pagelength="10"
   lengthmenu="5, 10, 20, 50, 100"
   columns="index, Topic, Description, Version, Release, Author"
}%
%ENDSECTION{"example3"}%

Selecting topics

%STARTSECTION{"example4"}%
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%" method="post">
%DATATABLE{
   web="System"
   class="foswikiFlatTable foswikiStripes"
   form="%SYSTEMWEB%.PackageForm"
   sort="TopicTitle"
   columns="index, TopicTitle, Description, Author, Changed"
   TopicTitle_title="Title" 
   info="on"
   paging="on" 
   rows="10"
   selecting="on"
   selectmode="multi"
   selectproperty="Topic"
   selection="%URLPARAM{"Topic"}%"
}%
%BUTTON{"%TRANSLATE{"Submit"}%" type="submit" icon="tick"}%
</form>
%ENDSECTION{"example4"}%

Topic		index	TopicTitle	Description	Author	Changed

Submit

Coloring rows using inline CSS

%STARTSECTION{"example5"}%
%DATATABLE{
   query="form~'FAQForm' AND topic!='FAQTemplate'"
   class="foswikiFlatTable foswikiStripes"
   web="%SYSTEMWEB%"
   paging="on"
   columns="Topic,TopicSummary,TopicClassification,Changed"
   TopicSummary_title="Summary"
   TopicClassification_title="Category"
   RelatedTopics_title="Related"
   rows="10"
   sort="TopicSummary"
   ordering="off"
   searching="on"
   rowcss="var css = { 
      'SupportQuestion': '#FFC107', 
      'FrequentlyAskedQuestion': {
         'background-color': '#4Caf40', 
         'color': '#fff'
      },
      'SupplementalDoc': '#f44336', 
      'AdminTopic': {
         'background-color': '#b22222',
         'color': '#fff'
      }
   }; return css[data.TopicClassification.raw];"
}%
%ENDSECTION{"example5"}%

Coloring rows using classes

This example is not fully working. It depends on a DataForm definition for Invoice topics, that have at least formfields

• Client: client that is invoiced
• Total: amount of money
• IssueDate: date when the invoice was sent to the client
• DueDate: date until when the invoice has to be paid
• State: the state the invoice is in: created, invoiced, overdue, reminded, disputed, paid, partial, withdrawn

We will use two properties of invoices to color the table. Depeding in the property values css classes will be applied that we crawft styles for. The invoice column will be colored depending on the State of an invoice. A blue line will be drawn below which all invoices have to be paid, that is the table will be devided in two parts below and above the line where above the line invoices will be paid in the future and below the line invoices should have to be paid up to today.

To make this work we create a small javascript fragment that returns the rowclass.

In addition, any client cell will auto-colored using Foswiki:Extensions/JQAutoColorContrib.

%STARTSECTION{"example6"}%
%DATATABLE{
   form="Invoice"
   class="foswikiFlatTable foswikiTable foswikiStripes"
   web="%SYSTEMWEB%"
   paging="on"
   columns="Topic,Client,Total,State,IssueDate,DueDate"
   rows="10"
   sort="DueDate"
   ordering="off"
   searching="on"
   autocolor="Client"
   rowclass="
      var now = Date.now() / 1000; 
      var cls = data.State.raw; 
      if (data.DueDate.epoch <= now) { 
         cls += ' past'
      }; 
      return cls; "
}%
%JQREQUIRE{"autocolor"}%
<style>
.dataTable tr.past {
  border-top: 3px solid #3e89d3;
}
.dataTable tr.past:first-of-type,
.dataTable tr.past + tr.past {
   border-top:0;
}
.dataTable tr.invoiced > td:nth-child(4) {
   background-color:#FFC107 !important;
}
.dataTable tr.reminded > td:nth-child(4) {
   background-color:#b22222 !important;
   color:#fff !important;
}
.dataTable tr.paid > td:nth-child(4) {
   background-color:#4Caf40 !important;
   color:#fff !important;
}
.dataTable tr.overdue > td:nth-child(4) {
   background-color:#f44336 !important;
   color:#fff !important;
}
</style>
%ENDSECTION{"example6"}%

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::JQueryPlugin	>= 4.10	Required
Foswiki::Contrib::JQMomentContrib	>= 3.00	Required
Foswiki::Plugins::MultiLingualPlugin	>= 4.00	Optional
Foswiki::Plugins::DBCachePlugin	>= 13.00	Optional
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required for Foswiki < 2.2

Change History

22 Jan 2024:	new perl api to register more datatable connectors; added parameter datetimeformat; fixed display of value-mapped columns/fields; fixed query builder of solr backend
23 Oct 2023:	add Web and TopicType columns
04 May 2022:	added DATATABLESECTION, ENDDATATABLESECTION, deprecate HTML5 approach; removed special / prefix from column names; new api Foswiki::Plugins::JQDataTablesPluginEnabled::describeColumn() to register custom datatable columns
06 Nov 2020:	don't return empty result rows as this breaks jquery.datatables; extended documentation of special column names
15 Oct 2020:	added buttons parameter and excel export; added parameters topics, include and exclude to DATATABLE macro; added support for multi-dimensional sorting (only available for DBCachePlugin connector); redesign of connector classes for better sortability & searchability: fixes SEARCH and SOLR backends
01 Jul 2019:	updated to latest upstream version of Datatables; added parameters rowgroup, rowclass, rowcss, hidecolumns and autocolor
07 Jan 2019:	added webs parameter to DATATABLE to query multiple webs at once
26 Nov 2018:	add docu for newly added savestate parameter to DATATABLE; fixed rendering image columns in DBCacheConnector
01 Oct 2018:	use JQMomentContrib for better parsing and sorting of date columns on the client side; make use of new TopicTitlePlugin; add support for MultiLingualPlugin
25 Sep 2017:	fixed html5 data attributes
30 Aug 2017:	disabled Author auto-column; added publishdate and publishauthor auto-columns
23 Jan 2017:	don't report back an url parameter in the error message
02 Sep 2016:	added default english translation files
13 Jun 2016:	fixed parsing of dates that are already epoch seconds; improved default settings of table layout
25 May 2016:	updated to latest version of DataTables
22 Apr 2016:	implemented server-side grid widget
18 Mar 2014:	remove console.log() leftover; improve sorting date columns
09 Nov 2013:	implemented sorting for currency, and metrics
08 Nov 2013:	make it work under {NoConflict}; enable jquery-ui theming by default now; created a non-goofy default look and feel to play nicely with a skin's table design; only add DataTables support to specific tables, not all; make it configurable with declarative metadata; compress and minify plugin assets; remove files not required by the plugin; clean up controls and css classes added by TablePlugin's; added type detector for foswiki date columns
18 Jan 2013:	Initial version