Help:Datatables format

From semantic-mediawiki.org
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, in the future, replacing the precursing result format "Datatables format (legacy)"A progressive table result printer that integrates the DataTables JavaScript library, 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 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 latest 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).

To enable specific Datatables plugins like SearchBuilder and Buttons add their symbol in the datatables-dom parameter, for instance using QfBrtip ("Q" represents SearchBuilder and "B" Buttons)

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 ask query
  • supports SearchPanes also used in conjunction with Ajax


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 thousand 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 exceeds 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
datatables-searchPanes.minCount include in searchPanes entries with occurrence greater or equal than "count" 1
datatables-searchPanes.htmlLabels enable/disable HTML in searchPanes false


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 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

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

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)

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


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 latest 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.


Datatables-v2-searchpanes-categories-dates-range.png


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.



General[edit]

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 the table result format with the "datatable" class differs from 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
NoteNote: The following parameters do not apply to this result format: headers and searchlabel despite them being listed here.


Known issues and limitations[edit]

  • Because browsed pages are cached client-side (within the scope of page reload), with the aim to not query the back-end while navigating the table, for pages already retrieved, and because the algorithm must take into account sorting, filtering, SearchPanes and Ajax, some navigation issue could occur with the current version. (expected to be fixed at the next update of the result format)
  • SearchPanes results slightly differ when they are or aren't used in conjunction with Ajax, since when the values are computed client-side, SearchPanes don't treat multiple values in the same column as distinct values. This usually produces minimal discrepancies, however a coming version of Datatables will offer a work-around if needed.
  • 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.


Design notes[edit]

Besides the natural benefit to use Datatables in conjunction with Semantic MediaWiki (because queries can be performed through an accessible query language, and saved within wiki pages), the current implementation try to further extend the functionality of Datatables, when used with Ajax, retrieving more rows than those required in each single page, and caching them until the page is reloaded, for a smoother and "friction-less" navigation. It also adds a few custom parameters, both at query level, and at printout level, to the native options included in the original Datatables library, like |+template=... (at printout level), datatables-searchPanes.minCount, datatables-searchPanes.htmlLabels (at query level), and more.


Demos[edit]


See also[edit]


References

  1. ^  Semantic MediaWiki: GitHub pull request gh:smw:2420