Json

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

Table and Datatables are typically used with the parser function visualdataquery (that as mentioned allows to query data from multiple pages). Since version 1.09 VisualData allows to display tables and datatables in two different mode: "plain" and "nested". (default is "auto", usually "plain" will be used if all the requested printouts are on the same hierarchical level, regardless of whether they are arrays or not). If set to "plain" the rows will be repeated in case of multiple entries and if set to "nested" multiple items are rendered in the same row.

Anyway the "plain" mode is encouraged by this format as a good practice, since tables should always contain same-level relationships and multiple tables also built from the same data should be used to display multi-level or hierarchical relationships.

Here is a parser function to display the data related to a specific article as a table:

{{#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's headings by default are the field labels as defined in the Schema Builder (if the label is not defined, the name will be used)
• pagetitle is always available and contains the link of the related wiki article.
• to disable the pagetitle column use the parameter pagetitle=
• each field name can be customized using the form name=alias where "name" is the original name and "alias" is the new assigned name
• to hide a given field but in the same time to retrieve its value to make it available as template parameter, use the following form name=
• 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 other computed properties, as named parameters, plus "pagetitle", "articleid", "isfirst" and "islast" (useful with arrays). 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.

Since version 1.09 table and datatable formats contain an additional parameter "mode" determining how entries are queried and shown in the table. If "auto" the mode will be automatically determined, if set to "plain" the rows will be repeated in case of multiple entries and if set to "nested" multiple items are rendered in the same row. See here https://wikisphere.org/wiki/Demo_VisualData/Test_table for a demo.

Datatable

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

Since version 1.08b datatables format also supports Searchpanes and Ajax navigation

Here are the available parameters:

Additionally, printout parameters in the style of SMW are also supported in the form:

?title |+datatables-columns.type=string |+datatables-width=50px 

(all those listed here https://datatables.net/reference/option/columns might be supported but haven't been extensively tested)

See here https://wikisphere.org/wiki/Demo_VisualData/Dynamic_catalogue for SearchPanes in action !!

Template

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 multiple subitems and a dedicated template must be used in this case, as described above.

Since version 1.0.9 all the parameters passed to a template by the visualdataquery parser function are visible using the parameters {{{params}}} or {{{_params}}} -- so that editors know which parameters are passed to the template and can use them properly.

For instance the output visible on the page using {{{params}}} inside https://wikisphere.org/wiki/Template:Book will be the following:

{
    "title": "The first men in the moon",
    "cover": "File:First_Men_in_the_Moon_(1901)_frontispiece.jpg",
    "authors": "
\nname: Herbert  Wells\n\nemail: \n
\nname: George Wells\n\nemail: \n
",
    "authors/1/email": "",
    "authors/1/first_name": "George",
    "authors/1/last_name": "Wells",
    "authors/1/name": "George Wells",
    "_title": "Demo VisualData",
    "_pagetitle": "Demo VisualData",
    "pagetitle": "Demo VisualData",
    "_pageid": 419,
    "pageid": 419,
    "articleid": 419,
    "_articleid": 419
}

(note that the sub-template inside the authors parameter/printout has been already expanded. Of course {{{params}}} or {{{_params}}} can be used in any sub-template as well)

For an interactive demo of a VisualData form that interactively changes the infobox data go here and press the button "Edit infobox and page".

Carousel

The carousel format allows to easily display images slideshow using the Slick Javascript library, out of lists of pictures (completed with title, caption, and link) recorded through VisualData. It has been inspired by the corresponding SMW result format, and it supports virtually all parameters of the Slick library using the prefix "slick-", as follows:

{{#visualdataprint: {{FULLPAGENAME}}
|schema=File upload  
|format=carousel  
|file-property=file       
|caption-property=caption   
|slick-autoplaySpeed=7000
|slick-dots=true 
|slick-adaptiveHeight=true
}}

(this parser function assumes that the current page has associated a schema named "File upload" with a property named "file" and a property named "caption": they can also be within an array)

Here are the available parameters. To find out more about each of them please check the official documentation of the Slick library.

See here https://wikisphere.org/wiki/Demo_VisualData/Carousel the Carousel in action !!

Map

The map format is a simple implementation of Leaflet and Leaflet.MarkerCluster (see also). Currently it does not include a geocoder, however for large data-sets it's a better practice to first retrieve the geolocation for your items, store it within your data, and use as needed. (VisualData includes however a Geolocation UI within forms, based on MapTiler).

The map format can be used in a visualdataquery as follows:

{{#visualdataquery: [[name::United States]]
|schema=Country       
|?states/name     
|?states/latitude    
|?states/longitude 
|template=Map popup 
|lat-property=latitude
|lon-property=longitude
|title-property=name
|markerCluster=false
|width=100%
|height=380px
|format=map
|limit=1000
}}

which retrieves all the states of a given country, completed with their geolocation (printouts states/latitude and states/longitude) and displays them through a map. The template parameter (if used) is only used to display the popup content for each item and it's exclusive with the title-property.

(See here https://wikisphere.org/wiki/Demo_VisualData/Dynamic_catalogue in action !!)

Raw

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) using the result of the query as part of the query of an outer visualdata query. See here for more information.

Lua

The Lua result format enables a module parameter to which the output of the query will be passed. It is intended for advanced users who needs to pre-process the result of the query using the flexibility of Lua scripting and to generate the output directly from the module. It can be used in the following way:

{{#visualdataquery:[[title::+]]
|schema=Book
|format=lua
|module=Handle query
|order=title asc
}}

then the query output can be accessed by the module Module:Handle query using

local origArgs = (type(frame.getParent) == "function") and frame:getParent().args or frame
local success, json = pcall(mw.text.jsonDecode, origArgs[0])

or

local json = mw.text.jsonDecode(origArgs[0])

Since version 1.08b a VisualData query can be performed directly from a Lua module using this code:

local ret = mw.visualdata.query( schema (string), query (string), printouts (list or table), params (table)  )

where the parameter query accepts the same format of the regular parser function (including a specific article id or title) the printouts expects a list of printouts (json paths without indexes) and the params accepts limit, order and offset.

count

Returns the number of results returned by the query.

pageid

Returns the pageid(s) of the matched article(s) by a query

pagetitle

Returns the article title(s) of the matched article(s) by a query

json-raw

Outputs the result in raw json (it is internally used by the function getQueryResults) and it is deprecated for the use in wiki articles in favor of the Lua format or the Lua function mw.visualdata.query.

table-raw

An internal result format used for the VisualData/API.

Custom result formats

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

See also

• Wikisphere demo Result formats
• New article UI
• Schema Builder
• File upload
• Edit data
• Forms
• Geolocation
• Queries
• Queries in forms
• Result formats
• Browse data
• Maintenance scripts
• Dynamic catalogue