Extension:VisualData/Result formats
Json
editJson 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
editTable 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-coverand 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
editAll 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
editThe 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
editThe 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.
| parameter | description | default |
|---|---|---|
| width | width of the carousel | 100%
|
| height | height of the carousel | |
| class | one or more classes applied to the container | |
| file-property | default property used for the file name | file
|
| title-property | default property used for the title | title
|
| caption-property | default property used for the caption | caption
|
| link-property | default property used for the link | link
|
| slick-accessibility | Enables tabbing and arrow key navigation. Unless autoplay: true, sets browser focus to current slide (or first of current slide set, if multiple slidesToShow) after slide change. For full a11y compliance enable focusOnChange in addition to this. | true
|
| slick-adaptiveHeight | Adapts slider height to the current slide | false
|
| slick-autoplay | Enables auto play of slides | true
|
| slick-autoplaySpeed | Auto play change interval | 3000
|
| slick-centerMode | Enables centered view with partial prev/next slides. Use with odd numbered slidesToShow counts. | false
|
| slick-centerPadding | Side padding when in center mode. (px or %) | 50px
|
| slick-cssEase | CSS3 easin | ease
|
| slick-dots | Current slide indicator dots | false
|
| slick-dotsClass | Class for slide indicator dots container | slick-dots
|
| slick-draggable | Enables desktop dragging | true
|
| slick-easing | animate() fallback easing | linear
|
| slick-edgeFriction | Resistance when swiping edges of non-infinite carousels | 0.15
|
| slick-fade | Enables fade | false
|
| slick-focusOnSelect | Enable focus on selected element (click) | false
|
| slick-focusOnChange | Puts focus on slide after change | false
|
| slick-infinite | Infinite looping | true
|
| slick-initialSlide | Slide to start on | 0
|
| slick-lazyLoad | Accepts 'ondemand' or 'progressive' for lazy load technique. 'ondemand' will load the image as soon as you slide to it, 'progressive' loads one image after the other when the page loads. | ondemand
|
| slick-mobileFirst | Responsive settings use mobile first calculation | false
|
| slick-nextArrow | Allows you to select a node or customize the HTML for the "Next" arrow. | <button type="button" class="slick-next">Next</button>
|
| slick-pauseOnDotsHover | Adapts slider height to the current slide | false
|
| slick-pauseOnFocus | Pauses autoplay when slider is focussed | true
|
| slick-pauseOnHover | Pauses autoplay on hover | true
|
| slick-prevArrow | Allows you to select a node or customize the HTML for the "Previous" arrow. | <button type="button" class="slick-prev">Previous</button>
|
| slick-respondTo | Width that responsive object responds to. Can be 'window', 'slider' or 'min' (the smaller of the two). | window
|
| slick-rows | Setting this to more than 1 initializes grid mode. Use slidesPerRow to set how many slides should be in each row. | 1
|
| slick-rtl | Change the slider's direction to become right-to-left | false
|
| slick-slide | Slide element query | |
| slick-slidesPerRow | With grid mode initialized via the rows option, this sets how many slides are in each grid row. | 1
|
| slick-slidesToScroll | # of slides to scroll at a time | 1
|
| slick-slidesToShow | # of slides to show at a time | 1
|
| slick-speed | Transition speed | 300
|
| slick-swipe | Enables touch swipe | true
|
| slick-swipeToSlide | Swipe to slide irrespective of slidesToScroll | false
|
| slick-touchMove | Enables slide moving with touch | true
|
| slick-touchThreshold | To advance slides, the user must swipe a length of (1/touchThreshold) * the width of the slider. | 5
|
| slick-useCSS | Enable/Disable CSS Transitions | true
|
| slick-useTransform | Enable/Disable CSS Transforms | true
|
| slick-variableWidth | Disables automatic slide width calculation | false
|
| slick-vertical | Vertical slide direction | false
|
| slick-verticalSwiping | Changes swipe direction to vertical | false
|
| slick-waitForAnimate | Ignores requests to advance the slide while animating | true
|
| slick-zIndex | Set the zIndex values for slides, useful for IE9 and lower | 1000
|
See here https://wikisphere.org/wiki/Demo_VisualData/Carousel the Carousel in action !!
Raw
editThis 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
editThe 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
editReturns the number of results returned by the query.
json-raw
editOutputs 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
editAn internal result format used for the VisualData/API.
Custom result formats
editSince 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
edit- 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
- ↑ Note that result printers belong to 2 different groups: hierarchical/nested result printers (like "json" and "template") and plain/flatted result printers (like "table" and "datatables"). The first groups the results by article/page, as Semantic MediaWiki, by contrast to the second group. Each group therefore invokes the query engine in different way and new result formats shall take that into account.