Extension:VisualData/Result formats

Currently VisualData supports the following result formats:

json
table
datatable
template
raw
query (internally used for results to be used in forms)

More result formats are expected to come in future releases of the extension, however the template and table/datatable formats are enough flexible to cover many use-cases.

Json edit

Json result format uses the Mediawiki's native implementation JsonContent::rootValueTable and is useful to print the data related to a single article especially with a hierarchical structure. Note indeed the parser function visualdataprint used to retrieve the data associated to the article "Demo_VisualData" (the first argument of the function)

{{#visualdataprint: Demo_VisualData
|?cover
|?title
|?authors/name
|?authors/email
|schema=Book
|format=json
}}

Shown data are automatically updated when the source data are edited through the tab "Edit data" or through a VisualData form editing the same data (namely using the parameter edit-page = {{FULLPAGENAME}}, or the name of the target page).

Table edit

Table and Datatables are typically used with the parser function visualdataquery (that as mentioned allows to query data from multiple pages). Note also that when used to print hierarchical or nested data the table will contain a row for each distinct value (rather than printing all different values of a given entry and property in the same cell) in such a way that either this format shouldn't be used to query hierarchical data, or the query should contain printouts (that is properties path, without indexes or json-schema keywords) on the same level or depth. This of course is made by purpose to encourage the use of tables with same-level data relationships, and/or the use of multiple tables, one for each set of data on the same level to be showcased, for the same set of data.

{{#visualdataprint: Demo_VisualData
|?cover
|?title
|?authors/name
|?authors/email
|schema=Book
|format=table
}}

(note that only the author's first name is different for each row, read above for more information)

Also note the following:

table headings are the field labels as defined in the Schema Builder (if the label is not defined, then the name will be used)
pagetitle is always available and contains the link of the related wiki article. To use a different name for the same column use the parameter pagetitle-name = [header name].
to disable the pagetitle column use the parameter pagetitle = false
the content of each cell can be further processed using a template. For instance to print the cover thumbnail in the Cover field, set a parameter like template?cover = Book-cover and then create a template with name "Book-cover" and content

[[{{{cover}}}|300px|frameless]]

Also note that in each referenced template are always available all the properties on the same level, as named parameters, plus "pagetitle", and "articleid" (as mentioned these parameter names can be customize using pagetitle-name = [name] and articleid-name = [name] to prevent names conflict when the json-schema properties uses the same names). This way each cell can reference all other cells for "endless" customization. See for instance here, a CRUD with a table cell containing another VisualData popup form, allowing to edit the row itself.

(see here for the template applied to the cell "action")

Note also that new empty cells can be simply added to the table requesting a non-existing printout in the same parser-function, like |?additional cell, then applying a template to the same cell (unless you don't want to keep it empty) and finally referencing other fields where required.

Datatable edit

All the features of the result format "table" are applicable to the result format "datatables" as well. Note that in this case makes more sense to use the parser function visualdataquery since a datatable is expected to contain also large set of data retrieved from multiple wiki articles. In this case therefore the first argument of the parser function is a query, the second argument as above is the schema, and the parameters starting with a question mark represent a printout. The current version of the extension does not allow Ajax navigation with Datatables, therefore it is recommended to add a parameter limit = 100. (or some reasonable limit)

{{#visualdataquery:[[name::Afghanistan]] [[states/name::Badakhshan]]
|schema=Country 
|?states/cities/name
|?states/cities/latitude
|?states/cities/longitude
|format=datatable 
}}

Template edit

The template result format is able to print hierarchical/nested data applying recursively specified templates for each of its components. This way is relatively easy to create/edit infoboxes also with one-to-many relationships, and possibly to appreciate them more (from the Enterprise MW Spring conference 2023).

{{#visualdataprint: Demo_VisualData
|?cover
|?title
|?authors/name
|?authors/email
|schema=Book
|template=Book
|template?authors=Book authors
|format=template
}}

In the related parser function there is a template applied at schema level, "Book", with the following content

{| class="wikitable infobox"
! Title
| {{{title}}}
|-
! Authors
| {{{authors}}}
|-
! Cover
| [[{{{cover}}}|center|200px]]
|}

and a template for the subitem authors with the following content

<div style="border:1px solid #ccc; padding: 12px">
name: {{{name}}}

email: {{{email}}}
</div>

It is important to note that the subitems "authors" are inserted in the root template through the corresponding named parameter, and that the parameters name of child items (name and email pairs), when accessed from the related template (called with the parameter template?authors=Book authors) correspond to the field names, not to the complete properties path (called "printout" in the dialect of VisualData).

As usual, in the same template other possible fields on the same level are available through their names, plus the standard parameters "pagetitle" and "articleid".

Since version 1.0.4 nested properties can be accessed with their complete path without the need to associate an additional template for that. E.g. when creating a Geolocation item, the latitude and longitude fields can be accessed from the root template simply through their named parameters {{{geolocation/latitude}}} and {{{geolocation/longitude}}}. This currently does not apply in case of arrays (multiple items) and a dedicated template must be used in this case, as described above.

Raw edit

This is just an alias for the template result formats, semantically used to print single value(s) either using or not separators. The following query for instance queries just the "title" property of a schema "Book" with data stored in the jsondata slot of the current article (as usual). The separators parameters are declared but won't have effect in this case.

{{#visualdataprint:{{FULLPAGENAME}} 
|schema=Book 
|format=raw 
|?title
|separator=<br />
|values-separator=,
|limit=1
}}

This kind of query is also useful to easily perform join queries in the controller itself (i.e. the template in Mediawiki's context, with reference of the MVC pattern). See here for more information.

Finally, because each format is internally implemented as a separate class, third party extensions can easily implement their own result formats by adding them to the global variable $GLOBALS['wgVisualDataResultPrinterClasses']['new-result-format] = NewResultFormat; and then creating a class (in this case "NewResultFormat") that extends MediaWiki\Extension\VisualData\ResultPrinter. ^[1]