Live Data Macro
Display dynamic lists of data. |
Type | JAR |
Category | Macro |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Bundled With | XWiki Standard |
Compatibility | Since 12.10.3 and 13.0. |
Table of contents
Description
Displays dynamic lists of data using various layouts (table, cards) providing support for pagination, selection (for batch actions), multi-sort, advanced filtering and in-line data editing.
Usage
id="recentPages"
properties="doc.title,doc.location,doc.author,doc.date"
source="liveTable"
sourceParameters="translationPrefix=platform.index."
filters="doc.location=help"
sort="doc.date:desc"
limit="5"
/}}
Parameters
Name | Description | Default Value | Since |
---|---|---|---|
id | The live data instance id. | ||
properties | The comma-separated list of properties to fetch and display. | ||
source | The live data source to use, specified as a component hint. | ||
sourceParameters | The live data source parameters, specified as an URL query string. | ||
filters | The initial filters to apply on the live data, specified as an URL query string. | ||
sort | The properties to sort on the live data initially, specified as a comma-separated list of property names, where each property name can be optionally suffixed with the sort order using :asc or :desc. | ||
limit | The maximum number of live data entries to show on a page. | 15 | |
offset | The index of the first live data entry to show. | 0 | |
layouts | The comma-separated list of layouts the user can choose from to display the live data. The first layout in the list will be loaded initially. | table,cards | |
showPageSizeDropdown | Show or hide the page size drop down that allows the user to change the number of entries displayed per page. | false | |
pageSizes | The comma-separated list of page sizes to display in the page size drop down. | 15,25,50,100 |
XWiki 12.10.3+, 13.0+
You can use the macro content to pass advanced Live Data configuration using the JSON format specified below.
"meta": {
"propertyDescriptors": [
{
"id": "actions",
"displayer": "html",
"sortable": false,
"filterable": false
}
]
}
}{{/liveData}}
The final configuration is obtained by merging the configuration build from the macro parameters with the configuration read from the macro content, giving priority to the former (i.e. macro parameters overwrite the corresponding advanced configuration property).
Live Data Sources
A live data source is implemented as a component and provides both the data (the live data entries) and information on how to interact with the data (how to display and edit the properties of a live data entry).
Here's a list of known live data sources:
- liveTable: exposes any live table results page as a live data source, allowing you to easily replace an existing live table with a live data instance.
- in-line data: the data is specified within the macro content, using the advanced live data configuration
Live Table Results
The liveTable live data source allows us to reuse any live table results page as a live data source. Moreover, you can preview the live data widget on any page that has a live table by adding useLiveData=true to the URL query string.
Examples
- Reuse the default live table results that correspond to a specified class name:{{liveData
id="users"
properties="_avatar,doc.name,first_name,last_name"
source="liveTable"
sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory."
/}} - Reuse custom live table results page:{{liveData
id="wikis"
properties="wikiprettyname,description,owner,doc.creationDate"
source="liveTable"
sourceParameters="resultPage=WikiManager.WikisLiveTableResults&className=XWiki.XWikiServerClass&translationPrefix=platform.wiki.browse."
/}} - Reuse custom live table results template:{{liveData
id="groups"
properties="name,members"
source="liveTable"
sourceParameters="template=getgroups.vm&translationPrefix=xe.admin.groups."
/}} - Reuse custom live table results page with advanced configuration:{{liveData
id="logging"
properties="logger,level,actions"
source="liveTable"
sourceParameters="resultPage=XWiki.LoggingAdminTableJson&translationPrefix=logging.admin.livetable."
}}{
"meta": {
"propertyDescriptors": [
{
"id": "actions",
"displayer": "html",
"sortable": false,
"filterable": false
}
]
}
}{{/liveData}}
Parameters
The liveTable live data source supports the following live table parameters:
- className
- resultPage
- queryFilters
- translationPrefix
Besides these, the following custom parameters are also supported:
Name | Description |
---|---|
template | Use this in case you have a live table with results generated from a Velocity template. The value of this parameter should match the template specified in the url live table configuration using the xpage query string. |
In-line Data
The live data can be specified in-line within the macro content, using the JSON format:
id="movies"
properties="title,genre,releaseDate,director"
}}{
"data": {
"count": 2,
"entries": [
{
"title": "Meet John Doe",
"url": "https://www.imdb.com/title/tt0033891/",
"genre": ["Comedy", "Romance"],
"releaseDate": -904615200,
"director": "Frank Capra",
"directorURL": "https://www.imdb.com/name/nm0001008/"
},
{
"title": "Modern Times",
"url": "https://www.imdb.com/title/tt0027977/",
"genre": ["Comedy", "Drama"],
"releaseDate": -1068256800,
"director": "Charlie Chaplin",
"directorURL": "https://www.imdb.com/name/nm0000122/"
}
]
},
"meta": {
"propertyDescriptors": [
{
"id": "title",
"name": "Title",
"visible": true,
"displayer": {"id": "link", "propertyHref": "url"}
},
{
"id": "genre",
"name": "Genre",
"visible": true
},
{
"id": "releaseDate",
"name": "Release Date",
"visible": true,
"displayer": "date"
},
{
"id": "director",
"name": "Director",
"visible": true,
"displayer": {"id": "link", "propertyHref": "directorURL"}
}
]
}
}{{/liveData}}
Layouts
The following layouts are currently supported:
Name | Description | Since |
---|---|---|
table | Displays the live data entries using a table, allowing the user to sort and filter from the table header. | |
cards | Displays the live data entries using cards arranged in a grid. Sorting and filtering is performed through dedicated panels that can be accessed from the live data menu. |
Table
Displays the live data entries using a table, allowing the user to sort and filter from the table header.
Cards
Displays the live data entries using cards arranged in a grid. Sorting and filtering is performed through dedicated panels that can be accessed from the live data menu.
Edit Mode
When a Live Data content is editable (i.e., if the content is allowed to be edited and the current user is allowed to edit it), double clicking on a content will switch it to edit mode. The content is then replaced by a form, allowing to update its content. Pressing escape will cancel the modification, and clicking outside the edited content will save the modifications and reload the Live Data to reflect the change.
Live Data JSON
The following JSON configuration is supported:
//
// The query
//
"query": {
// The list of properties to fetch.
"properties": ["title", "year", ...],
"source": {
// The component hint of the live data source
"id": "...",
// Parameters specific to each live data source implementation. This can also be used to implement hidden filters, that the user cannot change from the live data UI.
"customParam1": "...",
...
},
// Filter the live data entries.
"filters": [
{
"property": "title",
"matchAll": true,
"constraints": [
{"operator": "contains", "value": "help"},
],
},
],
// The list of properties to sort on.
"sort": [
{
"property": "birthdate",
"descending": false
},
],
// Indicates where the current page starts.
"offset": 0,
// The number of entries to fetch (the page size).
"limit": 10
},
//
// The data
//
"data": {
// The total number of entries available (on the server side).
"count": 54,
"entries": [
{
// property: value
"title": "Work from home",
"year": 2020,
...
},
...
],
},
//
// The meta data (used to control how we interact with the data)
//
"meta": {
"defaultLayout": "table",
"layouts": [
{
"id": "table",
"name": "Table",
"icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-table"},
},
{
"id": "cards",
"name": "Cards",
"icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-th"},
"titleProperty": "doc_title",
},
],
// Describes the properties that may appear in the data set. This determines the list of known (available)
// properties. Creating new properties, removing existing properties as well as editing the property descriptor
// should be done through this array.
"propertyDescriptors": [
{
// Identifies the property that this descriptor corresponds to.
"id": "title",
// The property name. Could be displayed before the property value.
"name": "Title",
// Could be displayed when hovering the property name.
"description": "...",
// Could be displayed before the property name, if specified.
"icon": {...},
// The property type, selected when creating the property. It is used to prefill the property descriptor.
// Could be mapped to an xclass property type.
"type": "String",
// Whether the user can sort on this property or not.
"sortable": true,
// Whether to show this property or not.
"visible": true,
// Displayer configuration.
"displayer": {
"id": "link",
// This is used only by the 'link' displayer (which receives the live data entry and the property descriptor).
"linkType": "..."
},
// Whether the user can filter by this property or not.
"filterable": true,
// Filter configuration.
"filter": {
"id": "text",
// This is used only by the 'text' filter (which receives the property descriptor).
"match": "prefix"
},
// Optional CSS class name to add to the HTML element used to display this property.
"styleName": "..."
}
],
// The list of known property types. When creating a new property the user can select from this list and the
// property descriptor will be prefilled based on the selected property type.
"propertyTypes": [
{"id": "string", "name": "String", "icon": {...}, "sortable": true, "displayer": {...}, "filterable": true, "filter": {...}},
...
],
"defaultFilter": "text",
// The list of known filters to choose from when editing the property descriptor.
"filters": [
{"id": "text", ...},
{"id": "date-range", ...},
{"id": "suggest", ...},
...
],
// The list of known property displayers to choose from when editing the property descriptor.
"displayers": [
{"id": "text", ...},
{"id": "html", ...},
{"id": "link", ...},
{"id": "actions", ...},
...
],
"defaultDisplayer": "text",
// Configure the pagination display.
"pagination": {
// The maximum number of page links to display in the pagination.
"maxShownPages": 10,
"pageSizes": [15, 25, 50, 100],
"showEntryRange": true,
"showNextPrevious": true,
"showFirstLast": false,
"showPageSizeDropdown": false,
},
"entryDescriptor": {
// The property that can be used to identify a live data entry. This is used for entry selection.
"idProperty": "doc.fullName",
},
// The list of actions known / supported by this live data instance. This is used by the actions displayer.
"actions": [
{
"id": "view",
"name": "View",
"description": "View entry",
"icon": {...},
"allowProperty": "doc.viewable",
"urlProperty": "doc.url"
},
...
],
// Selection configuration.
"selection": {
// Whether to enable or not the entry selection (e.g. for batch actions).
"enabled": false
}
}
}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-livedata-macro 13.3):
- org.xwiki.platform:xwiki-platform-livedata-api 13.3
- org.xwiki.platform:xwiki-platform-livedata-webjar 13.3
- org.xwiki.rendering:xwiki-rendering-transformation-macro 13.3
- org.xwiki.platform:xwiki-platform-skin-api 13.3