Extension:External Data/Retrieving and displaying data

External Data offers four basic ways to retrieve outside data and display it on the page: #external_value, #for_external_table, #display_external_table and #format_external_table (you can also use the #get_*_data functions to handle data retrieval; these functions are somewhat deprecated, but they still exist, and some of the documentation makes use of them). If Scribunto is installed, a Lua module can access external data by calling mw.ext.externalData.getExternalData().

The examples on this page all involve querying web data (the most popular data source), but External Data also supports retrieving data from many other data sources, including databases, LDAP servers and local files. For more information on these, and on web data retrieval itself, see the "Data sources" section in the navigation bar above.

Displaying individual values

To display just a single value from an outside source, call the following:

{{#external_value:local variable name|optional fallback value, which can contain wiki markup and even more calls of {{#external_value:}}}}

As an example, this page contains the following text:

Standalone mode

Legacy mode

* Germany borders the following countries: {{#arraymap:{{#external_value:Borders|source=https://discoursedb.org/GermanyCSV.txt|format=csv with header}}|,|x|[[x]]}}. * Germany has population {{#external_value:Population|source=https://discoursedb.org/GermanyCSV.txt}}. * Germany has area {{#external_value:Area|source=https://discoursedb.org/GermanyCSV.txt}}. * Its capital is {{#external_value:Capital|source=https://discoursedb.org/GermanyCSV.txt}}.

{{#get_web_data:url=https://discoursedb.org/GermanyCSV.txt|format=csv with header|data=bordered countries=Borders,population=Population,area=Area,capital=Capital}} * Germany borders the following countries: {{#arraymap:{{#external_value:bordered countries}}|,|x|[[x]]}}. * Germany has population {{#external_value:population}}. * Germany has area {{#external_value:area}}. * Its capital is {{#external_value:capital}}.

Note that, in the example above for the Standalone mode, |format= is given for the first call of #external_value, and that only for demonstration: in this case, the format can be auto-detected.

The page gets data from this URL, which contains the following text:

"357,050 km²","Austria,Belgium,Czech Republic,Denmark,France,Luxembourg,Netherlands,Poland,Switzerland",Berlin,"82,411,001"

The page then uses #external_value to display the 'bordered countries' and 'population' values; although it uses the #arraymap function, defined by the Page Forms extension, to apply some transformations to the 'bordered countries' value (you can ignore this detail if you want).

By default, #external_value displays an error message if it is called for a variable that has not been set, or if the specified data source is inaccessible, or the data source does not contain any data; and there is no fallback/default value. You can disable the error message by adding the following to LocalSettings.php:

$wgExternalDataVerbose = false;

See also Tag emulation mode.

Displaying a table of values

If you want to retrieve and display an entire "table" of data, you can use any of the functions #for_external_table, #display_external_table, or #format_external_table.

#for_external_table

This URL contains information similar to that above, but for a few countries instead of just one. Calling #get_web_data with this URL, with the same format as above, will set the local variables to contain arrays of data, rather than single values. You can then call #for_external_table, which can be called in one of the following two formats:

{{#for_external_table:|expression}}

Note that expression is the second parameter, while the first is empty. This is the recommended way to call this parser function, and templates and parser functions in expression, even wrapping the {{{variable}}} macros, will work intuitively;

{{#for_external_table:expression}}

The old way of calling the parser function, kept for backward compatibility, which does not correctly expand templates and parser functions receiving variables as arguments.

...where "expression" is a string that contains one or more macros.

A macro is a variable name, surrounded by triple brackets, optionally followed by a pipe and a default value used if the variable holds an empty value in the current loop, e.g. {{{var}}} or {{{var|default}}}. This string is then displayed for each retrieved "row" of data.

For an example, this page contains a call to #get_web_data for the URL mentioned above, followed by this call:

{| class="wikitable"
! Name
! Borders
! Population
! Area {{#for_external_table:|
{{!}}-
{{!}} {{{name}}}
{{!}} {{{borders}}}
{{!}} {{{population}}}
{{!}} {{{area}}}
}}
|}

The call to #for_external_table holds a single row of a table, in wiki-text; it's surrounded by wiki-text to create the top and bottom of the table. The presence of "{{!}}" is a standard MediaWiki trick to display pipes from within parser functions. There are much easier calls to #for_external_table that can be made, if you just want to display a line of text per data "row", but an HTML table is the standard approach.

There's one other interesting feature of #for_external_table, when it is called the old way, which is that it lets you modify specific values. You can URL-encode values by calling them with {{{field-name.urlencode}}} instead of just {{{field-name}}}, and similarly you can HTML-encode values by calling them with {{{field-name.htmlencode}}}. This fearure is not necessary in the recommended way of calling this parser function (with the second parameter), because {{urlencode:}}, {{htmlencode:}}, and any other parser function can be used as in any wikitext.

As an example of the former, if you wanted to show links to Google searches on a set of terms retrieved, you could call:

{{#for_external_table: http://www.google.com/search?q={{{term.urlencode}}} }}

This is required because standard parser functions can't be used within the first parameter of #for_external_table - so the following, for example, will not work:

{{#for_external_table: http://www.google.com/search?q={{urlencode:{{{term}}}}} }}

However, the simple and recommended way is using the second parameter:

{{#for_external_table:| http://www.google.com/search?q={{urlencode:{{{term}}}}} }}

Please, note also that, if the wiki markup is passed as the first parameter to the function, it is trimmed. So, if it is required to be a separate string, e.g., a forming a table row or a bulleted or ordered list item, it has to prepended with <nowiki />, to preserve the line break.

Example:

{| class="wikitable"
! Name
! Borders
! Population
! Area {{#for_external_table:<nowiki />
{{!}}-
{{!}} {{{name}}}
{{!}} {{{borders}}}
{{!}} {{{population}}}
{{!}} {{{area}}}
}}
|}

#display_external_table

#display_external_table is similar in concept to #for_external_table, but it passes the values in each row to a template, which handles the display. This function is called as:

{{#display_external_table: template=template name |data=set of parameters, separated by commas |delimiter=delimiter |intro template=template name (optional) |outro template=template name (optional) }}

An explanation of the parameters:

• |template= - the name of the template into which each "row" of data will be passed
• |data= - the data mappings between external variable and local template parameter; much like the data parameters for the other functions
• |delimiter= - the separator used between one template call and the next; default is a newline. (To include newlines in the delimiter value, use "\n".)
• |intro template= - a template displayed before the results set, only if there are any results
• |outro template= - a template displayed after the results set, only if there are any results

For example, to display the data from the previous example in a table as before, you could create a template called "Country info row", that had the parameters "Country name", "Countries bordered", "Population" and "Area", and then call the following:

Standalone mode	Legacy mode
{| class="wikitable" ! Name ! Borders ! Population ! Area {{#display_external_table: source=https://discoursedb.org/AfricaCSV.txt |format=CSV with header |data=Country name=Country,Countries bordered=borders,Population=population,Area=area |template=Country info row}} |}	{{#get_web_data:url=https://discoursedb.org/AfricaCSV.txt |format=CSV with header |data=Country name=Country,Countries bordered=borders,Population=population,Area=area }} {| class="wikitable" ! Name ! Borders ! Population ! Area {{#display_external_table:template=Country info row}} |}

The template "Country info row" should then contain wikitext like the following:

|-
|{{{Country name}}}
|{{{Countries bordered}}}
|{{{Population}}}
|{{{Area}}}

#format_external_table

#format_external_table is available, only if External Data ≥ 3.0 and Cargo ≥ 3.0 are installed. It passes the retrieved external data as a row-based two-dimensional array to the Cargo formatting engine, the same as used by the #cargo_query parser function. The function accepts the same parameters controlling the display as #cargo_query, as well as optional |data= which can be used to limit the number of displayed external variables, control their order and field aliases.

Example:

Standalone mode	Legacy mode
{{#format_external_table:source=https://expert.ru/avtory/konstantin_pakhunov/ |format=HTML |data=Title=article h2>a,URL=article h2>a.attr(href) |display format=table}}	{{#get_external_data: url=https://expert.ru/avtory/konstantin_pakhunov/ |format=HTML |data=title=article h2>a,url=article h2>a.attr(href) } {{#format_external_table:display format=table|data=Title=title,URL=url}}

In Lua, the Cargo Lua function mw.ext.cargo.formatTable (table, parameters) can be applied to the results returned by mw.ext.externalData.getExternalData () function family to achieve similar results.