Help:Datatables format

Datatables format
a complete porting of DataTables JavaScript library into SMW
Collection
Further Information
Provided by:	Extension "Semantic Result Formats"
Added:	4.0.2
Removed:	still supported
Requirements:	none
Format name:	datatables
Enabled? Indicates whether the result format is enabled by default upon installation of the respective extension.	yes
Authors:	thomas-topway-it for KM-A
Categories:	table
Group:	smwapi
Table of Contents

Starting with Semantic Result Formats 4.0.2, a full-fledged version of the powerful DataTables JavaScript library has been integrated to be available as a result printer. Besides the core library, the updated DataTables version includes a wide range of plugins and precisely:

• DataTables 1.13.2 (the core library)
• Buttons 2.3.4
• Column visibility 2.3.4
• HTML5 export 2.3.4
• Print view 2.3.4
• FixedColumns 4.2.1
• FixedHeader 3.3.1
• KeyTable 2.8.1
• Responsive 2.4.0
• RowGroup 1.3.0
• Scroller 2.1.0
• SearchBuilder 1.4.0
• SearchPanes 2.1.1
• Select 1.6.0
• StateRestore 1.2.1

All of them can be customized using the native Datatables options listed here through the "datatables-" prefix, to be used in the ask query, before the native datatable option. (for instance using datatables-pageLength=100 to set the default page length)

By contrast to the legacy version, still available using the format datatables-legacy, the latest version does not seek to introduce additional functionalities besides the base library (namely the "query-panel" and "instant update") but instead seeks to completely rely on the latest Datatables library and a large number of official plugins, which are now well developed and cover all querying requirements, including within the extent of SemanticMediaWiki.

Also, the latest version now produces results fully consistent with the base table format, (including the possibility to format the printouts using the standard Semantic MediaWiki modifiers) and relies on a dedicated Ajax Api in order to display tables of any length. (not limited by the limit set for inline ask queries, or the limit set as parameter).

To enable specific Datatables plugins like searchPanes add their symbol in the datatables-dom parameter, for instance using Pfrtip ("P" represents searchPanes)

Features

• cells content fully consistent with the standard SMW table format (including the use of Printouts format)
• can access all the rows of a query using Ajax when necessary
• supports navigation, filtering, and sorting against the complete data-set (using Ajax when necessary)
• supports sorting using multiple columns
• a wide range of native Datatables options are accessible through the askquery

Usage

{{#ask:
 [[Modification date::+]]
 |?Modification date
 |format=datatables
}}

Parameters

Format specific

parameter	description	default
class	adds additional classes to the table
mainlabel-template	template to be applied to the mainlabel. Use the canonical form |?=my label |+ template = my template to set multiple parameters	null
noajax	disable Ajax. Use this option wisely since when the data-set exceeds a few thousands rows the request might not complete	false
sep	separator for datavalues in the same column	 
defer-each	number of rows retrieved for each Ajax request (when the number of rows exceed the set limit) -- it can be greater than pageLength (see here for more information)	length required by Datatables (corresponding to pageLength or a greater value if scroller is enabled)
datatables-autoWidth	native Datatables option	false
datatables-deferRender	native Datatables option	false
datatables-info	native Datatables option	false
datatables-lengthChange	native Datatables option	true
datatables-ordering	native Datatables option	true
datatables-paging	native Datatables option	true
datatables-processing	native Datatables option	false
datatables-scrollX	native Datatables option	false
datatables-scrollY	native Datatables option	300px if Scroller is enabled
datatables-searching	native Datatables option	true
datatables-stateSave	native Datatables option	false
datatables-displayStart	native Datatables option	0
datatables-pagingType	native Datatables option	full_numbers
datatables-pageLength	native Datatables option	20
datatables-lengthMenu	native Datatables option	10, 20, 50, 100, 200
datatables-scrollCollapse	native Datatables option	false
datatables-scroller	native Datatables option	false
datatables-scroller.displayBuffer	native Datatables option	50
datatables-scroller.loadingIndicator	native Datatables option	false
datatables-buttons	native Datatables option
datatables-dom	native Datatables option	lfrtip
datatables-fixedHeader	native Datatables option	false
datatables-responsive	native Datatables option	true
datatables-keys	native Datatables option	false
datatables-columns.type	columns-type applied to all columns used for sorting ("auto", "any-number" plus the default types listed here). To set a column type for each column use the form |+datatables-columns.type = string besides the printout
datatables-columns.width	columns-width applied to all columns. To set a column width for each column use the form |+datatables-columns.width = 80px besides the printout
datatables-searchPanes	native Datatables option	false
datatables-searchPanes.initCollapsed	native Datatables option	true
datatables-searchPanes.collapse	native Datatables option	true
datatables-searchPanes.columns	native Datatables option, use a value in the form 0,2,3 to enable the searchPanes for the first, third and fourth column
datatables-searchPanes.threshold	native Datatables option	0.6
datatables-columns.searchPanes.show	enable the searchPanes for all columns, to enable the searchPanes for specific columns use datatables-searchPanes.columns or the form |+datatables-columns.searchPanes.show = true besides the printout

Printouts parameters

Printouts parameters are additional options for printouts in this form

|?=my label  |+ datatables-columns.type=string  |+ datatables-width=50px 
|?Modification date #-F[F j Y] = date |+template=mytemplate

Datatables (v2) supports virtually all the DataTables - Columns options listed here using the prefix |+ datatables-. However the most suitable for SMW ask query are the following (the prefix of the options "columns." can be omitted, so for instance columns.ariaTitle can be set using |+ datatables-ariaTitle=my title)

parameter	description (from the official docs)
columns.ariaTitle	Set the columns' aria-label attribute value
columns.className	Class to assign to each cell in the column.
columns.contentPadding	Add padding to the text content used when calculating the optimal width for a table.
columns.orderable	Enable or disable ordering on this column
columns.searchable	Enable or disable search on the data in this column
columns.title	Set the column title
columns.type	Set the column type - used for filtering and sorting string processing
columns.visible	Enable or disable the display of this column
columns.width	Column width assignment
columns.searchPanes.className	Add a custom class name to a pane
columns.searchPanes.collapse	Allow the SearchPanes to be collapsed for specific columns
columns.searchPanes.combiner	Set the type of logic to be implemented on the pane
columns.searchPanes.controls	Hide the Control buttons and disable searching in the pane of a specific column
columns.searchPanes.emptyMessage	Set custom empty messages for specific panes
columns.searchPanes.header	Set the title of the SearchPane
columns.searchPanes.hideCount	Deprecated. Hide the count column in the pane of a specific column
columns.searchPanes.initCollapsed	Collapse Specific SearchPanes on initialisation
columns.searchPanes.name	Set the name of the SearchPane
columns.searchPanes.orderable	Hide the ordering buttons in the pane of a specific column
columns.searchPanes.show	Force Panes to hide or show
columns.searchPanes.threshold	Set the minimum number of unique values needed in a specific column to display that pane
columns.searchPanes.viewCount	Hide the count column in the pane of a specific column

Additionally Datatables also supports the following printout parameter(s):

parameter	description (from the official docs)
template	Sets a template to be applied to the relevant printout, like in the form |?=my main label |+ template = my template (for the main label) or |?Organization name |+ template = my template (for usual properties)

Use this feature only with a single or a couple of columns in the table, with an undefined or low defer-each parameter, with an undefined or low limit, and with a low datatables-pagelength for it to work properly

General

Semantic MediaWiki 3.0.0Released on 11 October 2018 and compatible with MW 1.27.0 - 1.31.x. introduced a set of predefined classes supporting a datatable output1 in the result format "Table"Outputs the results in a table (default for queries with printout statements).. Note that using the table result format with the "datatable" class is different than using the datatables result format!

Parameter	Type	Default	Description
source	text	empty	Alternative query source
limit	whole number	50	The maximum number of results to return
offset	whole number	0	The offset of the first result
link	text	all	Show values as links
sort	list of texts	empty	Property to sort the query by
order	list of texts	empty	Order of the query sort
headers	text	show	Display the headers/property names
mainlabel	text	no	The label to give to the main page name
intro	text	empty	The text to display before the query results, if there are any
outro	text	empty	The text to display after the query results, if there are any
searchlabel	text	... further results	Text for continuing the search
default	text	empty	The text to display if there are no query results

  Note: The following parameters do not apply to this result format: headers and searchlabel despite them being listed here.

Demos

• https://fina.knowledge.wiki/Test_Datatables (Ajax navigation, sorting and filtering)
• https://fina.knowledge.wiki/Catalogues_of_Numismatic_Collections (searchPanes)
• https://silver.knowledge.wiki/User:Admin/Datatables_test (printout formats)

Limitations

• SearchPanes is currently disabled for tables requiring Ajax. This could be implemented in future. To overcome this limitation, set the parameter noajax to true (only for data-set of limited length -- 5,000-10,000 rows and provided that printouts templates aren't used)

Known issues

• Specific panes of searchPanes might not work if they contain html.

(both the limitations and the known issues are expected to be solved in future versions)

Development notes

See here for some development notes.

See also

• notes on the "datatable" class of the "table" result format