Help:Datatables format

From semantic-mediawiki.org
Jump to: navigation, search
Datatables format
A progressive table result printer that integrates the DataTables JavaScript library
Image collection
Further Information
Provided by: Semantic Result Formats
Added: 1.9.0
Removed: still supported
Requirements: none
Format name: datatables
Enabled by default: 
Indicates whether the result format is enabled by default upon installation of the respective extension.
yes
Authors: James Hong Kong
Categories: table
Group: smwapi
Class: SRF\DataTables, SMW\ApiResultPrinter
Folder: Commit history
Folder tree
Table of Contents

↓ INFO ↓

Starting with SMW/SRF 1.9, the powerful DataTables JavaScript library has been integrated to be available as a result printer. This result printer enables advanced interaction such as in-table search, on-the-fly filtering or variable length pagination.

This result printer is a full-fledged JavaScript result printer which works solely on the basis of interacting with the SMW through its SMWApi which makes this result printer less dependant on changes within SMW but also promotes data being dynamically refreshed and adopted while the page is being displayed.

  • In-table search
  • Result pagination
  • Instant update
  • Query panel

Query panel

Along with the DataTables plug-in, the query panel (see explanations or see the video on the left side) is an additional component that allows results to be adopted according to an user needs. Meaning that while the in-page #ask query will carry the responsibility of generating the base table content, content alteration can be achieved by adopting:

  • Parameters such as the limit parameter can be changed on-the-fly
  • Table content can be refreshed in a blink of an eye without the need to alter the #ask query
  • Conditions can be altered (this is only temporary until the next page refresh where the original conditions are restored)
  • If the user enables the auto-refresh functionality via his/hers user preferences, table content is automatically being refreshed during a page refresh/reload
  • If the user enables local storage support, result objects are stored for 15 min locally while image/thumbnail url information are stored for 24h. Disabling local storage will force the result printer always to request a server response instead of using available cache information.

Behind the curtain

UI components that are not part of the original DataTables library (such as the query panel or refresh button) are implemented as $.widget making it possible to separate display logic from table content.

srf.formats.datatables() contains all methods necessary to initialize the DataTables table as well as to ensure proper result object parsing, and update via Ajax.

Generally, the implementation was driven by the desire to ensure a responsive browser and page display behavior therefore in case of thumbnails those are successively loaded and placed within each cell after the table has been initialized in order to limit constraints during parsing and table content generation.

QUnit tests do accompany the implementation to ensure that elementary functions can be tested.

  • ext.srf.widgets.optionslist.test.js
  • ext.srf.widgets.panel.test.js
  • ext.srf.widgets.parameters.test.js
  • ext.srf.formats.datatables.test.js

Usage

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

Parameters

General

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

The headers (hide) option will be ignored as Datatables relies on referencing table content to a column (with a header).

Format specific

Parameter Type Default Description
class text empty Specify an additional cascading style sheet class
theme text bootstrap Select a grid theme

Configuration

User preferences

Available user preferences are described here.

Maximum number of results

Because the results are printed through a single inline query on a single page, the maximum number of rows printed is set by $smwgQMaxInlineLimit (500 by default) rather than $smwgQMaxLimit. The limit parameter will not normally help to increase the number beyond this limit, although this may work after the user has hit the refresh button in the top right.

Note

In-table images

Thumbnails (or in-table images) are queried after the table has been generated in order to keep the browser and the page responsive. Information about an image/thumbnail are requested via ajax after the table has been displayed which depending on the server response time can take a moment before all image links are replaced with its corresponding thumbnail. In case you use the local storage options, images information available to the cache should be available in an instant.

Issues with Safari on MW 1.27.x

In case the results are not loading properly you have to upgrade MediaWiki to version 1.27.2 or later or add the following configuration setting to your "LocalSettings.php" file:1$wgLegacyJavaScriptGlobals = false;

Limitations

  • Common wiki markup, such as that for italic or bold, is often not rendered by the datatables format. Some of the necessary tags, however, can be replaced using HTML text formatting in their stead (for instance, replace ''italic'' with <i>italic</i>).
  • This result format cannot represent values from
    • properties of type 'Record'
    • special properties such as "Has type" and "Subproperty of".

Examples


This documentation page applies to all SMW versions from 1.9.0 to the most current version.
     

Help:Datatables format en 1.9.0