"liveData" Macro
Reference
Description
Displays a list of entries fetched from a Live Data source, offering different layouts, pagination, entry selection, multi-property sorting, filtering and in-place editing.
The Macro is a block Macro: a Live Data always starts a new block.
Usage
Every parameter is optional. A call normally names the source the entries come from, its sourceParameters, and the properties to display:
{{liveData
id="..."
properties="..."
source="..."
sourceParameters="..."
filters="..."
sort="..."
limit="..."
/}}The Macro content may hold an advanced configuration, written as the JSON document described in Live Data Configuration. Where a parameter and that JSON set the same thing, the parameter wins.
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| id | No | Any name unique in the page | N/A | The id of the instance. Its display state is stored in the page URL under this id, so two instances in the same page must not share it. |
| properties | No | A comma-separated list of property ids | Every property the source declares | The properties to fetch and display, in display order. |
| source | No | The hint of a Live Data source | N/A | The source providing the entries, specified as a component hint. Without it the entries come from the in-line data in the Macro content. |
| sourceParameters | No | A URL query string | N/A | The parameters of the source. These are listed for specific sources in Live Data Sources. |
| filters | No | A URL query string of property=value pairs | N/A | The filters applied initially. Repeat a property to filter on several values. |
| sort | No | Property ids, each optionally suffixed with :asc or :desc | N/A | The properties to sort on initially, in order of precedence. |
| limit | No | A positive number | 15 | The number of entries per page. Query limits cap it at 1000 by default. |
| offset | No | A positive number | 0 | The index of the first entry to show. |
| layouts | No | A comma-separated list of layout ids | table,cards | The layouts the reader may choose from. The first of the list is displayed initially. |
| showPageSizeDropdown | No | true or false | false | Whether the reader can change the number of entries per page through a drop-down. |
| pageSizes | No | A comma-separated list of numbers | 15,25,50,100 | The values offered in that drop-down. |
| description | No | Any text | N/A | XWiki 16.0.0+ A description of the Live Data. It is displayed above the entries and is announced by assistive technologies as the description of the whole instance. |
Examples
Displaying the Pages Most Recently Changed in a Location
{{liveData
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"
/}}Listing the Users of the Wiki
{{liveData
id="users"
properties="_avatar,doc.name,first_name,last_name"
source="liveTable"
sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory."
/}}Restricting the Entries with an Initial Filter
{{liveData
id="users"
properties="_avatar,doc.name,first_name,last_name"
source="liveTable"
sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
/}}Filtering on Several Values of One Property
The tags property is filtered on two values and hidden, listing the pages tagged aaa or bbb without a tag column.
{{liveData
id="documents"
properties="doc.title,doc.date,doc.author,_actions,tags"
source="liveTable"
filters="tags=aaa&tags=bbb"
sourceParameters="className=XWiki.TagClass&translationPrefix=platform.index."
}}{
"meta": {
"propertyDescriptors": [
{
"id": "tags",
"visible": false
}
]
}
}{{/liveData}}Taking the Entries from a Custom Results Page
{{liveData
id="wikis"
properties="wikiprettyname,description,owner,doc.creationDate"
source="liveTable"
sourceParameters="resultPage=WikiManager.WikisLiveTableResults&className=XWiki.XWikiServerClass&translationPrefix=platform.wiki.browse."
/}}Taking the Entries from a Velocity Template
{{liveData
id="groups"
properties="name,members"
source="liveTable"
sourceParameters="template=getgroups.vm&translationPrefix=xe.admin.groups."
/}}Choosing the Displayer of One Property
The actions property holds HTML and should be neither sortable nor filterable.
{{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}}FAQ
Can the Macro be used inside a sentence?
No, it is a block Macro and always starts a new block.
A parameter and the Macro content set the same thing. Which one applies?
The Macro parameter, as explained in Live Data Configuration.
What happens if I set no parameter at all?
A call with no parameter is still valid: without source the entries come from the Macro content, and without properties every property the source declares is displayed.
Why are fewer entries displayed than the limit I set?
Because query limits cap the number of entries a page may display, at 1000 by default.
