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). 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=aliaswhere "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-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 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.
| parameter | description | default |
|---|---|---|
| mode | table mode: "auto", "plain" or "nested". If "plain" rows are repeated in case of multiple entries; if nested multiple items are rendered in the same row | auto
|
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:
| parameter | description | default |
|---|---|---|
| datatables-layout.topStart | https://datatables.net/reference/option/layout | pageLength
|
| datatables-layout.topEnd | https://datatables.net/reference/option/layout | search
|
| datatables-layout.bottomStart | https://datatables.net/reference/option/layout | info
|
| datatables-layout.bottomEnd | https://datatables.net/reference/option/layout | paging
|
| datatables-autoWidth | https://datatables.net/reference/option/autoWidth | false
|
| datatables-deferRender | https://datatables.net/reference/option/deferRender | false
|
| datatables-info | https://datatables.net/reference/option/info | true
|
| datatables-lengthChange | https://datatables.net/reference/option/lengthChange | true
|
| datatables-ordering | https://datatables.net/reference/option/ordering | true
|
| datatables-paging | https://datatables.net/reference/option/paging | true
|
| datatables-processing | https://datatables.net/reference/option/processing | false
|
| datatables-scrollX | https://datatables.net/reference/option/scrollX | false
|
| datatables-scrollY | https://datatables.net/reference/option/scrollY | false
|
| datatables-searching | https://datatables.net/reference/option/searching | true
|
| datatables-stateSave | https://datatables.net/reference/option/stateSave | false
|
| datatables-displayStart | https://datatables.net/reference/option/displayStart | 0
|
| datatables-pagingType | https://datatables.net/reference/option/pagingType | full_numbers
|
| datatables-pageLength | https://datatables.net/reference/option/pageLength | 10, 20, 50, 100, 200
|
| datatables-lengthMenu | https://datatables.net/reference/option/lengthMenu | false
|
| datatables-scrollCollapse | https://datatables.net/reference/option/scrollCollapse | false
|
| datatables-scroller | https://datatables.net/reference/option/scroller | false
|
| datatables-scroller.displayBuffer | https://datatables.net/reference/option/scroller.displayBuffer | 50
|
| datatables-scroller.displayBuffer | https://datatables.net/reference/option/ | 50
|
| datatables-scroller.loadingIndicator | https://datatables.net/reference/option/scroller.loadingIndicator | false
|
| datatables-buttons | https://datatables.net/reference/option/buttons -- supported buttons/formats are: colvis, copy, csv, excel, pdf and print | |
| datatables-fixedHeader | https://datatables.net/reference/option/fixedHeader | false
|
| datatables-responsive | https://datatables.net/reference/option/responsive | true
|
| datatables-keys | https://datatables.net/reference/option/keys | false
|
| datatables-columns.width | https://datatables.net/reference/option/columns.width | |
| datatables-searchPanes | https://datatables.net/reference/option/searchPanes | false
|
| datatables-searchPanes.emptyMessage | https://datatables.net/reference/option/searchPanes.emptyMessage | true
|
| datatables-searchPanes.collapse | https://datatables.net/reference/option/searchPanes.collapse | true
|
| datatables-searchPanes.columns | https://datatables.net/reference/option/searchPanes.columns | |
| datatables-searchPanes.threshold | https://datatables.net/reference/option/searchPanes.threshold | 0.6
|
| datatables-searchPanes.minCount | custom parameter | 1
|
| datatables-searchPanes.showEmpty | custom parameter | false
|
| datatables-searchPanes.htmlLabels | https://datatables.net/reference/option/searchPanes.htmlLabels | false
|
| datatables-cards | custom parameter (display rows as cards) | false
|
| datatables-synch | custom parameter (checks for new data each n seconds, if so it displays a button through which retrieve the original query through Ajax) | false
|
| datatables-synch.interval | custom parameter (datatables-synch interval, in seconds) | 100
|
| datatables-synch.property | special property (technically a "prefix") used to detect data changes, can be "Creation date" or "Modification date" | Creation date
|
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
|
| slick-enable-lazyLoad-after | enable lazy load after the given threshold | 10
|
See here https://wikisphere.org/wiki/Demo_VisualData/Carousel the Carousel in action !!
Map
editThe 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
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.
pageid
editReturns the pageid(s) of the matched article(s) by a query
pagetitle
editReturns the article title(s) of the matched article(s) by a 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.