Status: | effective |
Progress: | 100% |
Version: | 4.1.0+ |
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).
datatables-dom
parameter, for instance using Pfrtip
("P" represents searchPanes)
Features[edit]
- 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[edit]
{{#ask: [[Modification date::+]] |?Modification date |format=datatables }}
Parameters[edit]
Format specific[edit]
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[edit]
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[edit]
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 |

headers
and searchlabel
despite them being listed here.
Demos[edit]
- 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[edit]
- 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[edit]
- 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[edit]
See here for some development notes.
See also[edit]
- notes on the "datatable" class of the "table" result format
References
- ^ Semantic MediaWiki: GitHub pull request gh:smw:2420