Jump to content

Extension:External Data/Lua

From mediawiki.org

External Data defines a Lua function mw.ext.externalData.getExternalData() that fetches external data and returns it as a Lua table, so that wikis that have the Scribunto extension installed can call it to access and display outside data.

Additionally, in backward compatibility mode, the following functions are defined:

Lua function Corresponding parser function
mw.ext.externalData.getWebData {{#get_web_data:}}
mw.ext.externalData.getFileData {{#get_file_data:}}
mw.ext.externalData.getDbData {{#get_db_data:}}
mw.ext.externalData.getSoapData {{#get_soap_data:}}
mw.ext.externalData.getLdapData {{#get_ldap_data:}}
mw.ext.externalData.getProgramData {{#get_program_data:}}
mw.ext.externalData.getInlineData {{#get_inline_data:}}

The Lua functions accept the same parameters as parser functions, but please note the following:

  • Technically, there is only one parameter; it is known in Lua as a table, and its keys correspond to the parser function parameters.
    • If only one parameter source is sufficient for data retrieval (which is often the case due to auto-detection of format or that the parameters are set as a definition of a hidden data source in LocalSettings.php), it can be passed to the Lua function as its only string parameter: mw.ext.externalData.getExternalData 'https://discoursedb.org/GermanyCSV.txt'.
  • Comma-separated lists like data can be replaced with Lua tables; so that both data = {internal1 = 'external1', internal2 = 'external2'} and data = 'internal1=external1,internal2=external2' will work.
    • If XML format is used, an external variable __xml is set, which contains XML data preserving, with some limitations, the whole structure of the original XML document. It can be referred to in the data argument, and the corresponding internal variable will be a nested Lua table.
    • If JSON format is used, an external variable __json is set, which contains JSON data keeping the whole structure of the original JSON document. It can be referred to in the data argument, and the corresponding internal variable will be a nested Lua table.
    • If YAML format is used, an external variable __yaml is set, which contains YAML data keeping the whole structure of the original YAML document. It can be referred to in the data argument, and the corresponding internal variable will be a nested Lua table.
  • "Valueless" parameters like use xpath can be supplied both as numbered and named: 'use xpath' and ['use xpath'] = true are both valid.
  • Parameters whose name contains a space, like json offset, need to be surrounded with quotes and brackets, like ['json offset'] =, unless they are valueless, in which case quotes are enough.

Each Lua function returns two values:

  1. A table of external data. Unlike with the parser functions, it will be "row-based", i.e. a numbered array of records with named fields corresponding to external variables. If external data is not fetched, nil will be returned.
    • If there is only one value for some external variable (it will be in the first record), it will be duplicated as a named field of the returned table, as it is highly likely that it belongs to the rowset as a whole rather than its first row; so that it can be accessed both as tbl[1].external1 and tbl.external1,
  2. A numbered table of error messages. If there were no errors, nil will be returned.

Unlike parser functions, external data is only returned to calling Lua module and not stored on the page to be retrieved later by {{#external_value:}}, etc.

Example:

Lua code Return 
mw.ext.externaldata.getWebData {
    url = "https://discoursedb.org/wiki/Special:GetData/Fruits_data"
  , data = "name=Name,color=Color,shape=Shape"
  , format = "CSV with header"
}
or 
mw.ext.externaldata.getWebData {
    url = 'https://discoursedb.org/wiki/Special:GetData/Fruits_data'
  , data = {name = 'Name', color = 'Color', shape = 'Shape'}
  , format = 'CSV with header'
}

table#1 {
 table#2 {
   ["color"] = "Red",
   ["name"] = "Apple",
   ["shape"] = "Round",
 },
 table#3 {
   ["color"] = "Yellow",
   ["name"] = "Banana",
   ["shape"] = "Oblong",
 },
 table#4 {
   ["color"] = "Orange",
   ["name"] = "Orange",
   ["shape"] = "Round",
 },
 table#5 {
   ["color"] = "Yellow",
   ["name"] = "Pear",
   ["shape"] = "Pear-shaped",
 },

}, nil
local data, errors = mw.ext.externalData.getExternalData 'https://www.mediawiki.org/w/api.php?action=query&meta=siteinfo&format=json'
local json = not errors and data.__json or false
Wiki metadata from its API

See also the Cargo Lua function mw.ext.cargo.formatTable (table, parameters), which can be applied to the results returned by mw.ext.externalData.getExternalData () function family to format them Cargo way.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:External_Data/Lua&oldid=6583135"