Extension:External Data/Retrieving and displaying data

External Data offers four basic ways to retrieve outside data and display it on the page:,  ,   and   (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.

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:

As an example, this page contains the following text:

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:

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:
 * : Note that  is the second parameter, while the first is empty. This is the recommended way to call this parser functions, and templates and parser functions in , even wrapping the   macros, will work intuitively;
 * : 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.  or. 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:

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 instead of just , and similarly you can HTML-encode values by calling them with. This fearure is not necessary in the recommended way of calling this parser function (with the second parameter), because,  , 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:

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:

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

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, to preserve the line break.

Example:

#display_external_table
This function is called as:
 * 1) 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.

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


 * }

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

#format_external_table

 * 1) 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  which can be used to limit the number of displayed external variables, control their order and field aliases.

Example:

In Lua, the Cargo Lua function  can be applied to the results returned by   function family to achieve similar results.