View source for Help:Datatables format (legacy)

{{Result format
| format name=datatables-legacy
| authors=James Hong Kong
| minimum version=1.9.0
| maximum version=still supported
| further reqs=none
| is enabled=yes
| component=Semantic Result Formats
| categories=table
| group=smwapi
| description=A progressive table result printer that integrates the DataTables JavaScript library
| class=SRF\DataTables, SMW\ApiResultPrinter
| collection=datatables format
| video={{#widget:Vimeo|id=|width=230|height=220}}
| example=
| folder=formats/datatables-legacy
| panel=open
| video={{Video|provider=Vimeo|id=58518903|description=Short video how to use the datatables-legacy format|width=220|height=220}}
}}
Starting with [[Extension:Semantic Result Formats|Semantic Result Formats 1.9.0]], the powerful [[Help:Plug-ins|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.

{{Callout
 |In contrast to preceding versions, starting with [[Extension:Semantic Result Formats|Semantic Result Formats 4.1.0]] one needs to specify <code>datatables-legacy</code> instead of <code>datatables</code> for the "format" option on an [[Help:Inline queries|inline query]]. in contrast to preceding versions. Moreover, do not rely on this result format being available in future releases. Thus it is suggested to migrate to the new {{ResultFormat|datatables}}.
 |error
}}

{{Callout
 |{{Release|3.0.0|start}} introduced a set of predefined classes supporting a datatable output[[CiteRef::gh:smw:2420]] in the {{ResultFormat|Table}}. Note that the table result format with the "datatable" class differs from the datatables result format!
 |info
}}

== Features ==
This result printer is a full-fledged [[Help:Result formats|JavaScript result printer]] which works solely based on interacting with the Semantic MediaWiki through its [[:Category:API|SMWApi]], which makes this result printer less dependent on changes within Semantic MediaWiki 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 [[:File:Srf-format-datatables-query-panel-integration.png|explanations]] or see the video on the left side) is an additional component that allows results to be adapted according to a user needs. Meaning that while the in-page [[Help:Inline queries|inline queries using the <code>#ask</code> parser function]] query will carry the responsibility of generating the base table content, the content alteration can be achieved by adapting:
* 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 their user preferences, table content is automatically 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 is stored for 24h. Disabling local storage will force the result printer to always request a server response instead of using available cache information.

== Usage ==
<pre>
{{#ask:
 [[Modification date::+]]
 |?Modification date
 |format=datatables-legacy
}}
</pre>

== Parameters ==
=== General ===
{{#smwdoc:datatables-legacy|parameters=base}}

{{Note|The following parameters do not apply to this result format: <code>headers</code>, <code>link</code>, <code>order</code>, <code>searchlabel</code> and <code>sort</code> despite them being listed here.}}

=== Format specific ===
{{#smwdoc:datatables|parameters=specific}}

== Configuration ==
=== User preferences ===
Available user preferences are described [[Help:User preferences|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 {{Config|$smwgQMaxInlineLimit}} (500 by default) rather than {{Config|$smwgQMaxLimit}}. The <tt>limit</tt> parameter will not typically 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 to keep the browser and the page responsive. After displaying the table, information about an image/thumbnail is requested via [[ajax]]. Depending on the server response time, it can take a moment before all image links are replaced with their corresponding thumbnail. If you use the [[Help:User_preferences#Local_storage local storage|local storage]] options, image information available to the cache should be instantly available.

=== Issues with Safari on MW 1.27.x ===
In case the results are not loading correctly, you have to upgrade MediaWiki to version 1.27.2 or later or add the following configuration setting to your "LocalSettings.php" file:[[CiteRef::gh:srf:176:254289047]][[mws:Manual:$wgLegacyJavaScriptGlobals|<code>$wgLegacyJavaScriptGlobals = false;</code>]]

== Limitations ==
* Currently (as of SMW 2.5.x and SMW 2.4.x) default sorting of columns is not supported.[[CiteRef::mail:user:smw:td5074030]]
* 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 [http://www.w3schools.com/html/html_formatting.asp HTML text formatting] in their stead (for instance, replace <nowiki>''italic''</nowiki> with <nowiki><i>italic</i></nowiki>). 
* This result format cannot represent values from 
** properties of [[Help:Type Record|type 'Record']] and [[Help:Type Reference|type 'Reference']] (but can render their fields if specified with [[Help:Type_Record#Semantic_search|property-chain printouts]], like: <code>?record property.field property</code>).
** special properties such as "Has type" and "Subproperty of".

== Examples ==
{{#ask: [[Category:Datatables examples]]|format=ul}}
{{User preferences
|release=SRF 1.9.0
|context=Help:Datatables format
|description=Enable automatic updates during a page refresh
|name=srf-prefs-datatables-options-update-default
|default=no
}}{{User preferences
|release=SRF 1.9.0
|context=Help:Datatables format
|description=Enable to use of local caching
|name=srf-prefs-datatables-options-cache-default
|default=no
}}{{Plugin
 |title=jquery.dataTables.js
 |url=https://www.datatables.net/
 |licenses=MIT
 |description=JavaScript library for large table data manipulation
 |status=used by SMW
}}

== See also ==
* notes on the [[Help:Table_format#Format_specific|"datatable" class of the "table" result format]]
* notes on this [[Help:Datatables format/developer documentation|result format for developers]]
<div style="display: none">
{{DEFAULTSORTKEY:Datatables format}}
{{#scite:gh:srf:176:254289047
 |type=issuecomment
 |extension=Semantic Result Formats
 |url=https://github.com/SemanticMediaWiki/SemanticResultFormats/issues/176#issuecomment-254289047
}}
{{#scite:mail:user:smw:td5074030
 |type=mail
 |citation text=[http://wikimedia.7.x6.nabble.com/Default-sorting-in-datatables-result-format-td5074030.html Semantic MediaWiki: Default sorting in datatables result format]
}}
</div>
{{doc.info
 |master page=Help:Datatables format (legacy)
 |status=effective
 |progress=100
 |priority=2
 |minversion=1.9.0
}}