Status: | effective |
Progress: | 100% |
Version: | 4.1.0+ |
Datatables format | |
---|---|
Provides a complete porting of DataTables JavaScript library into Semantic MediaWiki | |
Collection | |
Further Information | |
Provided by: | Extension "Semantic Result Formats" |
Added: | 4.1.0 |
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.1.0, a full-fledged version of the powerful DataTables JavaScript library has been integrated, now replacing the precursing result format "Datatables format (legacy)"A progressive table result printer that integrates the DataTables JavaScript library. 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, the current version does not seek to introduce additional functionalities besides the base library (namely the "query-panel" and "instant update") but instead seeks to entirely 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 current version now produces results entirely 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 to display tables of any length. (not limited by the limit set for inline ask queries or the limit set as a parameter).
Features[edit]
- cells content fully consistent with the standard SMW table format (including the use of Printouts format)
- can access all the results 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 ask query
- supports SearchPanes also used in conjunction with Ajax
Latest features added:
- supports SearchBuilder (see here for a demo)
- adds mark.js (with native parameters, see SemanticResultFormats/pull/776)
- better accessibility: the table is first included in the article statically and then converted to a dynamic table
- supports Datatype Keyword with normalized values
- supports search of columns with multiple values
Usage[edit]
Minimal[edit]
{{#ask: [[Modification date::+]] |?Modification date |format=datatables }}
All options (does not include #Printouts parameters)[edit]
{{#ask: [[Modification date::+]] |?Modification date |format=datatables |class= |mainlabel-template= |noajax=false |sep=, |prefix=none |defer-each=0 |datatables-autoWidth=false |datatables-deferRender=false |datatables-info=true |datatables-lengthChange=true |datatables-ordering=true |datatables-paging=true |datatables-processing=false |datatables-scrollX=false |datatables-scrollY= |datatables-searching=true |datatables-stateSave=false |datatables-displayStart=0 |datatables-pagingType=full_numbers |datatables-pageLength=20 |datatables-lengthMenu=10, 20, 50, 100, 200 |datatables-scrollCollapse=false |datatables-buttons= |datatables-dom=lfrtip |datatables-fixedHeader=false |datatables-responsive=true |datatables-keys=false |datatables-columns.type= |datatables-columns.width=false |datatables-scroller=false |datatables-scroller.displayBuffer=50 |datatables-scroller.loadingIndicator=false |datatables-scroller.loadingIndicator=false |datatables-searchPanes=false |datatables-searchPanes.initCollapsed=false |datatables-searchPanes.collapse=true |datatables-searchPanes.columns= |datatables-searchPanes.threshold=0.6 |datatables-searchPanes.minCount=1 |datatables-searchPanes.htmlLabels=false |datatables-searchPanes.show= |datatables-searchBuilder=false |datatables-mark=false |datatables-mark.separateWordSearch=false |datatables-mark.accuracy=partially |datatables-mark.diacritics=true |datatables-mark.acrossElements=false |datatables-mark.caseSensitive=false |datatables-mark.ignoreJoiners=false |datatables-mark.ignorePunctuation= |datatables-mark.wildcards=disabled }}
Parameters[edit]
Format specific[edit]
parameter | description | data-type | default |
---|---|---|---|
class | adds additional classes to the table | string | |
mainlabel-template | template to be applied to the mainlabel. Use the canonical form |?=my label |+ template = my template to set multiple parameters |
string | null |
noajax | disable Ajax. Use this option wisely since when the data set exceeds a few thousand rows, the request might not complete | boolean | false |
sep | separator for datavalues in the same column | string | , 
|
defer-each | number of rows retrieved for each Ajax request (when the number of rows exceeds the set limit) -- it can be greater than pageLength (see here for more information) | integer | length required by Datatables (corresponding to pageLength or a greater value if scroller is enabled) |
Native datatables options[edit]
parameter | description | data-type | default |
---|---|---|---|
datatables-autoWidth | native Datatables option | boolean | false |
datatables-deferRender | native Datatables option | boolean | false |
datatables-info | native Datatables option | boolean | false |
datatables-lengthChange | native Datatables option | boolean | true |
datatables-ordering | native Datatables option | boolean | true |
datatables-paging | native Datatables option | boolean | true |
datatables-processing | native Datatables option | boolean | false |
datatables-scrollX | native Datatables option | boolean | false |
datatables-scrollY | native Datatables option | string | 300px if Scroller is enabled |
datatables-searching | native Datatables option | boolean | true |
datatables-stateSave | native Datatables option | boolean | false |
datatables-displayStart | native Datatables option | integer | 0 |
datatables-pagingType | native Datatables option | string | full_numbers |
datatables-pageLength | native Datatables option | integer | 20 |
datatables-lengthMenu | native Datatables option | comma separated values | 10, 20, 50, 100, 200 |
datatables-scrollCollapse | native Datatables option | boolean | false |
datatables-scroller | native Datatables option | boolean | false |
datatables-scroller.displayBuffer | native Datatables option | integer | 50 |
datatables-scroller.loadingIndicator | native Datatables option | boolean | false |
datatables-buttons | native Datatables option | comma separated values | |
datatables-dom | native Datatables option | string | lfrtip |
datatables-fixedHeader | native Datatables option | boolean | false |
datatables-responsive | native Datatables option | boolean | true |
datatables-keys | native Datatables option | boolean | 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 |
string | |
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 |
string |
Native SearchPanes options[edit]
parameter | description | data-type | default |
---|---|---|---|
datatables-searchPanes | Enable SearchPanes | boolean | false |
datatables-searchPanes.initCollapsed | native Datatables option | boolean | false |
datatables-searchPanes.collapse | native Datatables option | boolean | 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 |
comma separated values | |
datatables-searchPanes.threshold | native Datatables option | number | 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 |
boolean | |
datatables-searchPanes.minCount | include in searchPanes entries with occurrence greater or equal than "count" | integer | 1 |
datatables-searchPanes.htmlLabels | enable/disable HTML in searchPanes | boolean | false |
SearchBuilder options[edit]
parameter | description | data-type | default |
---|---|---|---|
datatables-searchBuilder | Enable SearchBuilder | boolean | false |
Native Mark.js options[edit]
parameter | description | data-type | default |
---|---|---|---|
datatables-mark | enable Mark.js | boolean | false |
datatables-mark.separateWordSearch | native Mark.js option Whether to search for each word separated by a blank instead of the complete term | boolean | |
datatables-mark.accuracy | native Mark.js option "partially", "complementary" or "exactly" | string | partially |
datatables-mark.diacritics | native Mark.js option | boolean | true |
datatables-mark.acrossElements | native Mark.js option | boolean | false |
datatables-mark.caseSensitive | native Mark.js option | boolean | false |
datatables-mark.ignoreJoiners | native Mark.js option | boolean | false |
datatables-mark.ignorePunctuation | native Mark.js option e.g. :;.,-–—‒_(){}[]!\'"+= | string | |
datatables-mark.wildcards | native Mark.js option | string | disabled |
datatables-searchPanes
requires to be set to true also if 'P' (the symbol for searchPanes in the dom option) appears in the datatables-dom
parameter
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
)
printout 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 search pane |
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 |
Here is/are the non datatables' native printout parameter(s):
printout parameter | description |
---|---|
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)
|
defer-each
parameter, with an undefined or low limit, and with a low datatables-pagelength
for it to work properly
SearchPanes[edit]
SearchPanes are a great way to interactively filter your results and to get an overview of each distinct values of your query! The current version of Datatables supports SearchPanes in conjunction with Ajax, and allows interactive filtering by categories and parameter formats, namely date-ranges, in addition than by all printouts included in the ask query.
In order to activate SearchPanes just add the parameter datatables-searchPanes=true
and Datatables will determine which panes to show based on the default uniqueness threshold value (it can be changed using datatables-searchPanes.threshold
for all printouts, or using |+ datatables-searchPanes.threshold
for a specific printout, if set to 1 the pane will be always shown). Also use it in conjunction with |+ datatables-searchPanes.show
besides each specific printout, in order to enable/disable panes in a granular way.
Date-ranges work setting a printout format like the following |?Modification date #-F[Y] = Year
, or |?Modification date #-F[F Y] = Year
, so that values are grouped by year in the first case, and month + year in the second one. (See here for a demo).
SearchPanes make your data more accessible, however a threshold greater than the default should be judiciously used, especially on medium-large data-sets, and consequently they should be kept disabled for the mainlabel (since page titles are always unique) and unless they aren't grouped in some way through the printout format.
A good rule-of-thumb is to activate SearchPanes, also on large data-sets, only for those printouts/columns that have a limited number of distinct values, i.e. not more than a few hundreds, where 50 should be considered an appropriate limit for a good user experience, that is where users can meaningfully play with SearchPanes, and to explicitly disable them for other columns using |+ datatables-searchPanes.show = false
.
SearchBuilder[edit]
SearchBuilder allows to filter the table results by setting one or more conditions for a given field, and to define the logical operator (between 'And' and 'Or') between them. To activate it just set datatables-searchBuilder=true
among the ask query's parameters. Then press the "Add condition" button to search the table using conditions!
This is by adding a condition:
Internally the conditions set by the SearchBuilder are transformed to SMW queries according to the following algorithm:
$str = ( $label !== '' ? "$label::" : '' ); switch( $criteria['condition'] ) { case '=': $searchBuilder[] = "[[{$str}{$v}]]"; break; case '!=': $searchBuilder[] = "[[{$str}!~$v]]"; break; case 'starts': $searchBuilder[] = "[[{$str}~$v*]]"; break; case '!starts': $searchBuilder[] = "[[{$str}!~$v*]]"; break; case 'contains': $searchBuilder[] = "[[{$str}~*$v*]]"; break; case '!contains': $searchBuilder[] = "[[{$str}!~*$v*]]"; break; case 'ends': $searchBuilder[] = "[[{$str}~*$v]]"; break; case '!ends': $searchBuilder[] = "[[$str}!~*$v]]"; break; // case 'null': // break; case '!null': if ( $label ) { $searchBuilder[] = "[[$label::+]]"; } break; }
where $label
is the printout related to the given field and $v
is the search value. In short SearchBuilder is a great way (as SearchPanes) to use complex SMW queries through a simple interface. See here for a demo.
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.
Known issues and limitations[edit]
- SearchPanes might not work correctly with large data-sets or complex queries. In the first case, the responsibility to use SearchPanes only when the data include a reasonable number of distinct values is left to administrators, and in the second case it could be solved in future adding standard methods to SMW in order to safely manipulate SQL queries generated by Ask queries.
- With the current version, only few of the available formats for specific printout types, are supported, i.e., they are handled correctly in queries performed by SearchPanes. Feel free to open a ticket in the official repository if you need to support more.
- Sometimes a changed value is not ready displayed due to the MediaWiki cache system. For instance, if you use
$wgMainCacheType = CACHE_ACCEL;
in yourLocalSettings.php
, try disable it with$wgMainCacheType = CACHE_NONE;
(the default value).
Design notes[edit]
Datatables is a natural fit for Semantic MediaWiki because queries can be performed through an accessible query language and saved within wiki pages. The current implementation also extends the functionality of Datatables:
- when used with Ajax, it can retrieve more rows than those required in each single page and for a smoother and 'friction-less' navigation, it caches them until the page is reloaded.
- it also adds a few custom parameters, at both query level and printout level, to the native options included in the original Datatables library. For instance,
|+template=...
(at printout level)datatables-searchPanes.minCount
,datatables-searchPanes.htmlLabels
(at query level).
Demos[edit]
- Multiple filters and Ajax navigation: https://fina.knowledge.wiki/Test_Datatables
- SearchPanes: https://fina.knowledge.wiki/Test_Datatables/SearchPanes_Categories
- SearchBuilder:https://fina.knowledge.wiki/Catalogues_of_Numismatic_Collections/SearchBuilder
- Printout formats: https://silver.knowledge.wiki/User:Admin/Datatables_test
- Noajax (all data are retrieved on page load) https://fina.knowledge.wiki/Catalogues_of_Numismatic_Collections
References
- ^ Semantic MediaWiki: GitHub pull request gh:smw:2420