Ready for review

Point the Live Data Macro page at the new Live Data documentation

Last modified by Eleni Cojocariu on 2026/09/10 21:40

Manage
- Copy
Actions
Viewers
- Source
- Children
- Information
- Likes

Merge this after its companion on www.xwiki.org, Live Data documentation migration, which creates the 14 pages this change points at. Until that one is published none of those targets exists, and this page is still the only copy of the material.

This is the second half of that conversion, and it is a separate change request only because a change request cannot carry pages from two wikis of the farm.

The whole description xproperty (43,307 characters, 42 sections) was converted, so every section is replaced here by a pointer at the page that now owns it:

Sections	Now at
Usage, In Wiki Syntax, Parameters, Examples	Display a List of Data in a Page and "liveData" Macro
Using Velocity, Script Service	Live Data Script Service
Live Data Sources, Live Table Results, Properties from Other Classes	Live Data Sources and Migrate a Live Table to Live Data
Layouts, Table, Cards, Selection	Live Data Layouts
Properties Panel, Sort Panel, Filter Panel	Live Data Panels
In-place Edit	Edit a Value in Place
Edit Mode	Edit Several Entries at Once
In-line Data, Macro Configuration guide, Actions, Live Data JSON, Async Actions, Colored icons	Live Data Configuration
JavaScript, JavaScript API, Html Structure	Live Data JavaScript API
Adding a Panel, Vue Components Loading, LiveTable New Row Naming Strategy	Live Data Extension Points
Troubleshooting, Live Table Source	Debug the SQL Query of a Live Data
Persistent State, User Features, Developer Features	the user and developer hubs

Every heading is kept, in its original order and byte for byte, including the ones whose body is now a single pointer. A heading's HTML id is generated from its text, so removing one would break every link aimed at it, and the Backlinks list never shows anchors. Order matters too: Parameters appears three times and Example/Examples twice, and XWiki numbers the repeated ids by position.

website is set to the "Documentation" button, as on Panels Application and Icon Theme Application. Note what that does: ExtensionCode.ExtensionSheet hides the description and its heading while website is non-empty, on purpose, so the pointer skeleton above is the stored fallback rather than what a reader sees. It also means the page's #H… anchors stop resolving, which is why the backlinks have to be re-pointed without them.

Only description and website are posted. Every other xproperty, the 7 dependency xobjects, the proxy xobject and the sheet binding are left exactly as they are, and the page is not deleted: it still carries the extension's own metadata.

Two things this change deliberately does not do, both because a file change cannot express them:

the page's 12 attachments (liveData-*.png, cards-no-entries.png, table-no-entries.png) are no longer referenced by anything and have to be deleted, which a file change cannot do. The new pages carry their own re-captured screenshots, so nothing is lost by deleting them after this merges.
the backlinks of this page still have to be triaged: prose links that mean "read about this" re-pointed at the new pages without their #H… anchor, links that mean "install this extension" left alone. extensions.xwiki.org currently answers a Cloudflare interstitial to the Information tab, so that list has to be read from a browser.

Eleni Cojocariu created this Change Request with changes for Live Data Macro 3 hours ago

All changes

Summary

Page properties (1 modified, 0 added, 0 removed)
Objects (1 modified, 0 added, 0 removed)
- ExtensionCode.ExtensionClass[0]

Details

Page properties

Author

@@ -1,1 +1,1 @@
--xwiki:XWiki.Admin
++xwiki:XWiki.elenicojocariu

ExtensionCode.ExtensionClass[0]

Description

@@ -1,1112 +1,169 @@
--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.
++See [[Live Data>>xwiki:documentation.xs.user.livedata.WebHome]].
--{{info}}
--The Live Data feature is a replacement for the older [[Live Table feature>>Extension.Livetable Macro]]. You should migrate to use Live Data as Live Table will be removed eventually.
--{{/info}}
--
  = Usage =
++See [[Display a List of Data in a Page>>xwiki:documentation.xs.user.livedata.display-data.WebHome]].
++
  == In Wiki Syntax ==
--{{code language="none"}}
--{{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"
--/}}
--{{/code}}
++See [["liveData" Macro>>xwiki:documentation.xs.user.livedata.display-data.macro.WebHome]].
  == Using Velocity ==
--{{version since="16.0.0RC1"}}
--(((
--{{warning}}
--Whenever XWiki syntax is available, it is preferable to use the macro instead of the Velocity script service.
++See [[Live Data Script Service>>xwiki:documentation.xs.dev.livedata.script-service.WebHome]].
--The script service should be used only when the macro cannot be used (for example in ##.vm## templates, rendering macros cannot be used and only Velocity scripting can be used).
--{{/warning}}
--)))
--
--{{code language="velocity"}}
--$services.liveData.render({
--  '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
--})
--{{/code}}
--
--See the [[Script Service>>||anchor="HScriptService"]] section for more details.
--
--{{image reference="liveData-table.png"/}}
--{{/version}}
--
  == 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>>Extension.Component Module]] hint.| |
--|sourceParameters|The live data source parameters, specified as a URL query string.| |
--|filters|The initial filters to apply on the live data, specified as a 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. {{version since="16.10.11,17.4.4,17.7.0RC1"}}[[Query limits>>extensions:Extension.Query Module||anchor="HQueryLimits"]] apply to the limit, by default at maximum 1000 entries can be displayed on a page.{{/version}}|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|
--|description|An optional textual description of the Live Data.| |16.0.0
++See [["liveData" Macro>>xwiki:documentation.xs.user.livedata.display-data.macro.WebHome]].
--You can use the macro content to pass advanced Live Data configuration using the JSON format specified [[below>>||anchor="HLiveDataJSON"]].
--
--{{code language="none"}}
--{{liveData ...}}{
--  "meta": {
--    "propertyDescriptors": [
--      {
--        "id": "actions",
--        "displayer": "html",
--        "sortable": false,
--        "filterable": false
--      }
--    ]
--  }
--}{{/liveData}}
--{{/code}}
--
--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>>Extension.Component Module]] 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).
++See [[Live Data Sources>>xwiki:documentation.xs.user.livedata.display-data.sources.WebHome]].
--Here's a list of known live data sources:
--
--* ##liveTable##: exposes any [[live table>>Extension.Livetable Macro]] 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>>Extension.Livetable Macro]] 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.
++See [[Live Data Sources>>xwiki:documentation.xs.user.livedata.display-data.sources.WebHome]] and [[Migrate a Live Table to Live Data>>xwiki:documentation.xs.user.livedata.migrate-live-table.WebHome]].
  === Examples ===
--* Reuse the default live table results that correspond to a specified class name:(((
--{{code language="none"}}
--{{liveData
--  id="users"
--  properties="_avatar,doc.name,first_name,last_name"
--  source="liveTable"
--  sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory."
--/}}
--{{/code}}
--)))
--* Result the default live table results that correspond to a specific class name, with a filter on a property:(((
--{{code language="none"}}
--{{liveData
--  id="users"
--  properties="_avatar,doc.name,first_name,last_name"
--  source="liveTable"
--  sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
--/}}
--{{/code}}
--)))
--* Reuse the default live table results that correspond to a specified class name, from another wiki in the farm:(((
--{{code language="none"}}
--{{liveData
--  id="users"
--  properties="_avatar,doc.name,first_name,last_name"
--  source="liveTable"
--  sourceParameters="className=XWiki.XWikiUsers&resultPage=xwiki:XWiki.LiveTableResults&translationPrefix=xe.userdirectory."
--/}}
--{{/code}}
--))){{warning}} This is a workaround for the bug [[XWIKI-22688>>https://jira.xwiki.org/browse/XWIKI-22688]]. You'll probably also need to set your displayer manually.{{/warning}}
--* Reuse custom live table results page:(((
--{{code language="none"}}
--{{liveData
--  id="wikis"
--  properties="wikiprettyname,description,owner,doc.creationDate"
--  source="liveTable"
--  sourceParameters="resultPage=WikiManager.WikisLiveTableResults&className=XWiki.XWikiServerClass&translationPrefix=platform.wiki.browse."
--/}}
--{{/code}}
--)))
--* Reuse custom live table results template:(((
--{{code language="none"}}
--{{liveData
--  id="groups"
--  properties="name,members"
--  source="liveTable"
--  sourceParameters="template=getgroups.vm&translationPrefix=xe.admin.groups."
--/}}
--{{/code}}
--)))
--* Reuse custom live table results page with advanced configuration:(((
--{{code language="none"}}
--{{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}}
--{{/code}}
--)))
--* Display all pages having a tag with value "aaa" or value "bbb" (but don't display a tag column):(((
--{{code language="none"}}
--{{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}}
--{{/code}}
--)))
++See [["liveData" Macro>>xwiki:documentation.xs.user.livedata.display-data.macro.WebHome]].
  === Parameters ===
--The ##liveTable## live data source supports the following [[live table parameters>>Extension.Livetable Macro||anchor="HParameter24options"]]:
++See [[Live Data Sources>>xwiki:documentation.xs.user.livedata.display-data.sources.WebHome]].
--* className
--* resultPage
--* queryFilters (default value: ##currentlanguage,hidden##)
--** see [[Extension.Query Module]] for more details on the filters
--** with those filters, the content is translated to the locale of the user and hidden pages are only displayed when ##Display hidden pages## is set to ##Yes## in the user preferences
--* 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.
--|hasEditMode|{{version since="18.7.0RC1"}}If set to ##true##, enable the Live Data to enter [[Edit mode>>||anchor="HEditMode"]] (default value: ##false##).{{/version}}
--|newRowNamingStrategy|{{version since="18.7.0RC1"}}Strategy to use to generate page names when creating new rows. Right now, the only value supported is ##uuid## which uses a random UUID for each new page and create them in the location set by ##newRowLocation##.{{/version}}
--|newRowLocation|{{version since="18.7.0RC1"}}Location to store pages when creating new rows. Requires a compatible row naming strategy, //e.g.//, ##uuid##.{{/version}}
--
--The ##extraParams## live table parameter is not listed above because its main usage is filtering, and the live data has its own **generic** way to perform filtering. If you're migrating a live table that uses ##extraParams## to live data then you should:
--
--* try to convert the ##extraParams## used for filtering to live data filters (e.g. by using the ##filters## live data macro parameter)
--* try to pass the rest of the ##extraParams## directly as live data source parameters, **BUT** there's no guarantee that they will have the same effect on the live data
--
--Example of a code using originally extraParams:
--
--{{code}}
--{{velocity}}
--#set ($options = {
--  'className': 'ExtensionCode.ExtensionVersionClass',
--  'location': "${doc.space}"
--})
--
--{{liveData
--  id="versions"
--  properties="version,notes"
--  source="liveTable"
--  sourceParameters="$services.rendering.escape($escapetool.url($options), 'xwiki/2.1')"
--/}}
--
--{{/velocity}}
--{{/code}}
--
--{{version since="18.0.0RC1"}}
  ==== Properties from Other Classes ====
--Similar to the possibility to specify custom classes for single properties with ##myProperty_class## parameters in LiveTable with ##extraParams##, it is possible to specify a property-specific class in Live Data. For this, pass the ##myProperty_class=MySpace.MyClass## parameter in the source parameters. Properties from other classes support filtering, sorting and editing. When a displayed document doesn't yet have an object of the specified class, it is created when the property is saved.
++See [[Live Data Sources>>xwiki:documentation.xs.user.livedata.display-data.sources.WebHome]].
--As an example, with the following Live Data you can get an index of all pages with the tags being displayed if there are any. If there are no tags on a page, an object is automatically added for them when they are edited.
--
--{{code language="none"}}
--{{liveData properties="doc.location,doc.title,tags" source="liveTable" sourceParameters="tags_class=XWiki.TagClass&translationPrefix=platform.index."/}}
--{{/code}}
--{{/version}}
--
  == In-line Data ==
--The live data can be specified in-line within the macro content, using the JSON format:
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
--{{code language="none"}}
--{{liveData
--  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}}
--{{/code}}
--
--{{warning}}
--Please note that In-Line Data [[currently does not support filtering, sorting, or pagination>>https://jira.xwiki.org/browse/XWIKI-19783]]. Therefore, it is recommended to deactivate these features to avoid unexpected error messages when the table Topbar and the Buttombar is used. While filtering and sorting are disabled by default if not set, pagination must be explicitly disabled in the "meta" section of the JSON configuration:
--
--{{code language="none"}}
--…
--"pagination": {
--  "showEntryRange": false,
--  "showNextPrevious": false,
--  "showFirstLast": false
--}
--…
--{{/code}}
--
--If you want to avoid also displaying the remaining and buggy Page Counter or hide the entire Topbar/Bottombar without disabling pagination in the JSON configuration, you can achieve this using a XWiki.StyleSheetExtension for that specific page, as documented in the [[Skin Extension Tutorial>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/SkinExtensionsTutorial/]]:
--
--{{code language="none"}}
--.livedata-topbar {display: none !important;}
--.livedata-bottombar {display: none !important;}
--{{/code}}
--{{/warning}}
--
  = User Features =
++See [[Live Data>>xwiki:documentation.xs.user.livedata.WebHome]].
++
  == Layouts ==
--The live data can be displayed using multiple layouts. The following layouts are currently supported:
++See [[Live Data Layouts>>xwiki:documentation.xs.user.livedata.layouts.WebHome]].
--|=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. The user can also change the column (property) order and resize the columns with drag and drop or keyboard arrows. To reset the column width you can double click on the resize handler that is visible when hovering the column header, or press Escape when focusing it.
++See [[Live Data Layouts>>xwiki:documentation.xs.user.livedata.layouts.WebHome]].
--{{image reference="liveData-table.png"/}}
--
--This layout is responsive on small screens.
--
--{{image reference="liveData-table-responsive.png"/}}
--
--When the Live Data is empty, a message is displayed at the bottom.
--
--{{image reference="table-no-entries.png"/}}
--
  === 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. The user can change the property order using drag & drop.
++See [[Live Data Layouts>>xwiki:documentation.xs.user.livedata.layouts.WebHome]].
--{{image reference="liveData-cards.png"/}}
--
  == Properties Panel ==
--The Properties panel, accessible from the hamburger menu on the right, allows you to hide / show live data properties and to change their order with drag & drop. Changing the property order is also possible directly from the Table and Cards layouts using the 3-dot icon that is visible when hovering the property name (column name).
++See [[Live Data Panels>>xwiki:documentation.xs.user.livedata.panels.WebHome]].
--{{image reference="liveData-panel-properties.png"/}}
--
--When the Live Data is empty, a message is displayed at the bottom.
--
--{{image reference="cards-no-entries.png"/}}
--
  == Sort Panel ==
--The Sort panel allows you to sort on multiple properties, provided the properties are sortable and provided the live data source supports sorting on single or multiple properties. Some layouts, like the Table layout, might have shortcuts for sorting (e.g., click on the column header).
++See [[Live Data Panels>>xwiki:documentation.xs.user.livedata.panels.WebHome]].
--{{image reference="liveData-panel-sort.png"/}}
--
  == Filter Panel ==
--The Filter panel allows you to filter on multiple properties. For each property you can add multiple constraints, provided the property is filterable (as indicated by the live data configuration). Some layouts, like the Table layout, might have shortcuts for filtering (e.g., the filter row below the table header). The filter input (widget) depends on the property type and on the constraint operator. The following filter widgets are currently supported: text, number, list (suggest), date, boolean.
++See [[Live Data Panels>>xwiki:documentation.xs.user.livedata.panels.WebHome]].
--{{image reference="liveData-panel-filter.png"/}}
--
  == In-place Edit ==
--When the live data is editable (i.e., if the live data source supports updating the data and the current user is allowed to make changes), double-clicking on a property value (e.g., on a table cell in the table layout) will switch that property to edit mode. The displayed property value is then replaced by a form, allowing you to update the property value. Pressing the ##escape## key will cancel the modification and switch back to display value. Clicking outside the edited content will save the modifications and reload the live data to reflect the change.
++See [[Edit a Value in Place>>xwiki:documentation.xs.user.livedata.edit-value-place.WebHome]].
--When a property of a Live Data is editable (i.e., if the Live Data source supports updating the data and the current user is allowed to make changes), hovering on an editable property value (e.g., on a cell in the table layout) shows a popover containing an edit action button. Clicking on this button switches the property to edit mode, displaying a form allowing to update the property value in-place. Pressing the ##escape## key will cancel the modification and switch back to display value. Clicking outside the edited content will save the modifications and reload the live data to reflect the change.
--On touch-based devices, the popover is displayed when touching an editable property. In addition, touching a link contained on any Live Data property shows the popover too, with a follow link action (when touching a link inside an editable property, both actions are proposed in the popover).
--
  == Selection ==
--When selection is enabled, the user can select live data entries.
++See [[Live Data Layouts>>xwiki:documentation.xs.user.livedata.layouts.WebHome]].
--{{image reference="liveData-table-selection.png"/}}
--
  == Persistent State ==
--The current page URL is updated whenever the live data state changes through pagination, sorting, filtering, hiding or re-ordering properties, etc. which means the live data state is bookmarkable. The live data state is preserved if you reload the page or if you give the page URL to someone else.
++See [[Live Data>>xwiki:documentation.xs.user.livedata.WebHome]].
  == Edit Mode ==
--{{version since="18.7.0RC1"}}
--Edit mode is a mode that helps with bulk editing, that can be toggled on a Live Data that explicitly supports it (//e.g.//, with the live table source, by setting the ##hasEditMode## [[source parameter>>||anchor="HParameters-1"]] to ##true##).
++See [[Edit Several Entries at Once>>xwiki:documentation.xs.user.livedata.edit-mode.WebHome]].
--{{image reference="liveData-editMode-toggle.png"/}}
--
--In this mode, all hidden columns are forcefully displayed, and clicking any editable cell directly opens it in edit mode. It's also possible to navigate between cells with the keyboard through Tab/Shift+Tab, with every switch saving the previously focused cell and opening the editor on the newly focused one.
--
--For sources that also support row creation (//e.g.//, live table with a properly configured ##newRowNamingStrategy## [[source parameter>>||anchor="HParameters-1"]]), a **+ Add entry** button is also available at the bottom of the table for users that have enough rights to create new content.
--
--{{image reference="liveData-addEntry.png"/}}
--
--Clicking it will create a draft row, with cells that can be navigated either by mouse or keyboard. Once all the necessary data has been set, it can be saved either by clicking on the **✓** action button on the right, or with keyboard: Return to validate, or Ctrl+Return to validate and create a new draft row again. There is also a **✗** action button on the right to cancel and delete the draft row.
--
--{{image reference="liveData-rowDraft.png"/}}
--
--{{/version}}
--
  = Macro Configuration guide =
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
++
  == Actions ==
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
++
  === Allow an action ===
--The action descriptors have a ##allowProperty## field. This field references another property of the entry, holding a boolean value indicating whether the action is allowed for the current entry.
--See the example below for an action ##A## with an allow property ##allowA##.
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
--{{code language="json"}}
--{
--  "data": {
--    "count": 2,
--    "entries": [
--      {
--        "title": "Allowed Entry",
--        "allowA": true
--      },
--      {
--        "title": "Disallowed Entry",
--        "allowA": false
--      }
--    ]
--  },
--  "meta": {
--    "propertyDescriptors": [
--      {
--        "id": "title",
--        "type": "String"
--      },
--      {
--        "id": "allowA",
--        "type": "Boolean"
--      },
--      {
--        "id": "_actions",
--        "name": "_actions",
--        "visible": true,
--        "displayer": { "id": "actions", "actions": ["actionA"] }
--      }
--    ],
--    "entryDescriptor": {
--      "idProperty": "title"
--    },
--    "actions": [
--      {
--        "id": "actionA",
--        "name": "Action A",
--        "description": "Perform action A",
--        "allowProperty": "allowA"
--      }
--    ]
--  }
--}
--{{/code}}
--
  = Developer Features =
++See the [[Live Data>>xwiki:documentation.xs.dev.livedata.WebHome]] developer documentation.
++
  == Live Data JSON ==
--The following JSON configuration is supported:
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
--{{code language="js"}}
--{
--  //
--  // 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 user can edit in-place this property (the user also need to have the right to edit a given entry to edit it).
--        "editable": true,
--
--        // Whether to show this property or not.
--        "visible": true,
--
--        // Displayer configuration.
--        "displayer": {
--          "id": "link",
--
--          // Indicates the property whose value is the URL that should be used as the link target (e.g. 'doc.url').
--          "propertyHref": "...",
--
--          // Whether to allow HTML in the link content, used by the 'link' displayer
--          "html": true
--        },
--
--        // 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", ...},
--      {"id": "list", ...},
--      {"id": "number", ...},
--      {"id": "boolean", ...},
--      ...
--    ],
--
--    // The list of known property displayers to choose from when editing the property descriptor.
--    "displayers": [
--      {"id": "text", ...},
--      {"id": "html", ...},
--      {"id": "link", ...},
--      {"id": "actions", ...},
--      {"id": "date", ...},
--      {"id": "boolean", ...},
--      {"id": "number", ...},
--      {"id": "docTitle", ...},
--      {"id": "xObjectProperty", ...},
--      ...
--    ],
--
--    "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"
--      },
--      // Specify the edit action with an allowProperty to control who can in-place edit the entries
--      // By default, the action is allowed.
--      {
--        "id": "edit",
--        "allowProperty": "doc.editable"
--      }
--      ...
--    ],
--
--    // Selection configuration.
--    "selection": {
--      // Whether to enable or not the entry selection (e.g. for batch actions).
--      "enabled": false
--    }
--  }
--}
--{{/code}}
--
  == Script Service ==
--{{code language="java"}}
--/**
-- * Scripting APIs for the Live Data component.
-- *
-- * @since 12.10
-- */
--@Component
--@Named("liveData")
--@Singleton
--public class LiveDataScriptService implements ScriptService
--{
--    /**
--     * Executes a live data query.
--     *
--     * @param queryConfig the live data query configuration
--     * @return the live data entries that match the given query
--     */
--    public LiveData query(Map<String, Object> queryConfig)
--    {
--        // ...
--    }
++See [[Live Data Script Service>>xwiki:documentation.xs.dev.livedata.script-service.WebHome]].
--    /**
--     * Executes a live data query.
--     *
--     * @param queryConfigJSON the live data query configuration
--     * @return the live data entries that match the given query
--     */
--    public LiveData query(String queryConfigJSON)
--    {
--        // ...
--    }
--
--    /**
--     * Computes the effective live data configuration by normalizing the given configuration (i.e. transforming it to
--     * match the format expected by the live data widget) and adding the (missing) default values.
--     *
--     * @param liveDataConfig the live data configuration to start with
--     * @return the effective live data configuration, using the standard format and containing the default values
--     */
--    public Map<String, Object> effectiveConfig(Map<String, Object> liveDataConfig)
--    {
--        // ...
--    }
--
--    /**
--     * Computes the effective live data configuration by normalizing the given configuration (i.e. transforming it to
--     * match the format expected by the live data widget) and adding the (missing) default values.
--     *
--     * @param liveDataConfigJSON the live data configuration to start with
--     * @return the effective live data configuration, using the standard format and containing the default values
--     */
--    public String effectiveConfig(String liveDataConfigJSON)
--    {
--        // ...
--    }
--
--    /**
--     * Execute the Live Data and return a {@link Block}.
--     *
--     * @param parameters the parameters to pass to the Live Data renderer
--     * @return the Live Data {@link Block}
--     * @throws LiveDataException in case of error when rendering the Live Data
--     * @since 16.0.0RC1
--     */
--    @Unstable
--    public Block execute(Map<String, Object> parameters) throws LiveDataException
--    {
--        // ...
--    }
--
--    /**
--     * Execute the Live Data and return a {@link Block}.
--     *
--     * @param parameters the parameters to pass to the Live Data renderer
--     * @param advancedParameters the advanced parameters to pass to the Live Data renderer
--     * @return the Live Data {@link Block}
--     * @throws LiveDataException in case of error when rendering the Live Data
--     * @since 16.0.0RC1
--     */
--    @Unstable
--    public Block execute(Map<String, Object> parameters, Map advancedParameters) throws LiveDataException
--    {
--        // ...
--    }
--
--    /**
--     * Renders a Live Data.
--     *
--     * @param parameters the parameters to pass to the Live Data executor. The parameters cae
--     * @return the result of {@link #execute(Map)} in the current syntax
--     * @throws LiveDataException in case of error when rendering the Live Data
--     * @since 16.0.0RC1
--     */
--    @Unstable
--    public String render(Map<String, Object> parameters) throws LiveDataException
--    {
--        // ...
--    }
--
--    /**
--     * Renders a Live Data.
--     *
--     * @param parameters the parameters to pass to the Live Data executor
--     * @param advancedParameters the advanced parameters to pass to the Live Data executor
--     * @return the result of {@link #execute(Map, Map)} in the current syntax
--     * @throws LiveDataException in case of error when rendering the Live Data
--     * @since 16.0.0RC1
--     */
--    @Unstable
--    public String render(Map<String, Object> parameters, Map advancedParameters) throws LiveDataException
--    {
--        // ...
--    }
--}
--{{/code}}
--
--Example of using the script service :
--
--{{code}}
--{{velocity}}
--  #set($properties = {
--    "id" : "users",
--    "properties" : "_avatar,doc.name,first_name,last_name",
--    "source" : "liveTable",
--    "sourceParameters" : "className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
--  })
--  {{html}}
--    $services.liveData.render($properties)
--  {{/html}}
--{{/velocity}}
--{{/code}}
--
--is the equivalent of :
--
--{{code}}
--{{liveData
--  id="users"
--  properties="_avatar,doc.name,first_name,last_name"
--  source="liveTable"
--  sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
--/}}
--{{/code}}
--
--And another example of using the script service :
--
--{{code}}
--{{velocity}}
--  #set($properties = {
--    "id" : "logging",
--    "properties" : "logger,level,actions",
--    "source" : "liveTable",
--    "sourceParameters" : "resultPage=XWiki.LoggingAdminTableJson&translationPrefix=logging.admin.livetable."
--  })
--  #set($advancedProperties = {
--    "meta": {
--      "propertyDescriptors": [
--        {
--          "id": "actions",
--          "displayer": "html",
--          "sortable": false,
--          "filterable": false
--        }
--      ]
--    }
--  })
--  {{html}}
--    $services.liveData.render($properties, $advancedProperties)
--  {{/html}}
--{{/velocity}}
--{{/code}}
--
--is the equivalent of :
--
--{{code}}
--{{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}}
--{{/code}}
--
--
  == JavaScript ==
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
++
  === JavaScript API ===
--{{version since="14.4RC1"}}
--Live Data provides a JavaScript API that is accessible on the container of the instance via the jQuery data-property ##liveData## (e.g., ##jQuery("#wikis").data("liveData")##) and in [[Live Data events>>xwiki:Documentation.DevGuide.FrontendResources.JavaScriptAPI.WebHome||anchor="HLiveDataevents28Logic.js29"]].
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
  ==== getLayoutIds ====
--Returns the list of available layouts ids.
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
--Example:
--
--{{code language="javascript"}}
--jQuery("#myld").data("liveData").getLayoutIds();
--{{/code}}
--
  ==== getPropertyDescriptors ====
--Get the list of property descriptors.
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
--Example:
--
--{{code language="javascript"}}
--jQuery("#myld").data("liveData").getPropertyDescriptors();
--{{/code}}
--
  ==== updateEntries ====
--Reload the Live Data according to its current filters and sort configuration.
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
--Example:
--
--{{code language="javascript"}}
--jQuery("#myld").data("liveData").updateEntries();
--{{/code}}
--
  === Adding a Panel ===
--It is possible to extend Live Data by adding new panels that can be toggled via the menu via the ##registerPanel## method, the following demonstrates a simple "Hello World"-panel:
++See [[Live Data Extension Points>>xwiki:documentation.xs.dev.livedata.extension-points.WebHome]].
--{{code language="js"}}
--document.addEventListener('xwiki:livedata:instanceCreated', function(e) {
--  const panel = {
--    id: 'myExtension',
--    name: 'My Extension',
--    title: 'Hello World',
--    icon: 'camera',
--    container: document.createElement('div'),
--    component: 'LiveDataAdvancedPanelExtension',
--    order: 4000
--  };
--
--  panel.container.textContent = 'Hello World!';
--
--  e.detail.livedata.registerPanel(panel);
--});
--{{/code}}
--
--The id must be unique among all panels, the name is the text that is displayed in the menu, the title the text that is displayed in the title of the panel. The icon is displayed in the menu and the panel's title. The order is the display order for the panels, the default properties, sort and filter panels have order 1000, 2000 and 3000. The ##container## must be a DOM node, it is automatically attached to the panel's body when it is not collapsed, when the panel is collapsed the ##container## will be detached. The component should be ##LiveDataAdvancedPanelExtension## for the supported API but in theory could be any Vue component. Note, however, that while Live Data is currently based on Vue 2 it will be upgraded to Vue 3 at some point which might break custom components, the component's API isn't considered stable. All properties of the panel must be present when it is registered but, apart from the order, they can be changed later, changes will be reflected in the UI. This could be used, e.g., to add and update a counter in the name or title.
--{{/version}}
--
  == Async Actions ==
--{{version since="16.2.0RC1"}}
--Is it possible to define an action as asynchronous. In this case, instead of following the link, the action will be performed in the background. The Live Data is refreshed once the asynchronous action is successful.
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
  === Parameters ===
--The parameters are to be added to the ##async## key of the action, located in the ##meta.actions## array. The URL is the one resolved through the ##urlProperty## of the action.
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
--* ##httpMethod##: the HTTP method to use to call the action URL
--* ##loadingMessage##: the localized message to display while the action is running asynchronously
--* ##successMessage##: the localized message to display once the action finished successfully
--* ##failureMessage##: the localized message to display once the action finished unsuccessfully
--* ##body##: (optional) a value to use in the request body
--* ##headers## (optional) a map of headers to use for the request
--
  === Example ===
--{{code language="none"}}
--{{liveData
--  id="test"
--  properties="name,_actions"
--  source="liveTable"  sourceParameters="className=Space.MyClass"
--}}{
--  "meta": {
--    "actions": [{
--        "id": "delete",
--        "async": {
--          "httpMethod": "POST",
--          "loadingMessage": "Loading",
--          "successMessage": "Delete Success",
--          "failureMessage": "Failed",
--          "body": "newBacklinkTarget=&updateLinks=false&autoRedirect=false&form_token=${services.csrf.token}&confirm=1&async=true",
--          "headers": {
--            "Content-Type": "application/x-www-form-urlencoded"
--          }
--        }
--      }]
--  }
--}
--{{/liveData}}
--{{/code}}
--{{/version}}
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
  == Colored icons ==
--{{version since="16.3.0RC1"}}
--Is is possible to add additional classes on icons (in addition to the one possible introduced by the icon sets) by adding the ##extraIconClasses## property on icon descriptors.
++See [[Live Data Configuration>>xwiki:documentation.xs.dev.livedata.configuration.WebHome]].
--On the example below, we add the ##tex-danger## class on the ##delete## action, making the delete action icon displayed in the danger color (i.e., red by default).
--{{code language="none"}}{"id": "delete", "icon": "cross", "extraIconClasses": "text-danger"}{{/code}}
--{{/version}}
--
  == Html Structure ==
--This section lists interesting attributes that are useful to perform preciser selection of Live Data elements while staying agnostic of a given layout.
++See [[Live Data JavaScript API>>xwiki:documentation.xs.dev.livedata.javascript-api.WebHome]].
--* {{version since="16.2.0RC1"}}##data-livedata-property-id## attribute added on all property displayers. Contains the ID of the displayer.{{/version}}
--* {{version since="15.10.1"}}##data-livedata-entry-index## attribute added to the root element of an entry. Contains the index of the displayed entry for the current pagination.{{/version}}
--* {{version since="15.10.1"}}##data-livedata-entry-id# attribute added to the root element of an entry. Contains the value of the identifier of the displayed entry.{{/version}}
--
  == Vue Components Loading ==
--{{version since="17.4.0RC1"}}
--Globally loading components with {{code language="javascript"}}Vue.component('ComponentName', Component);{{/code}} is not possible anymore with Vue 3.
++See [[Live Data Extension Points>>xwiki:documentation.xs.dev.livedata.extension-points.WebHome]].
--A component store is now provided by Live Data, allowing for the registration of new displayers.
--
--##componentsStore.register(string, string, () => Promise<VueComponent>)##
--
--* **kind: string**: any of ##filter##, ##layout##, or ##displayer##, defines the type of loaded component
--* **name: string**: the name of the registered component
--* **loader: () => Promise<VueComponent>**: a function returning a ##VueComponent## wrapped in a promise. This allows for the lazy loading of components, only when effectively loaded (see ##load## below=
--
--##componentsStore.load(string, string): Promise<VueComponent>##
--
--* **kind: string**: the kind of component to load
--* **name: string**: the name of the component to load
--* **returns**: a Promise with the resolved components if found, ##undefined## otherwise
--
--**Example:**
--
--{{code language="javascript"}}
--import { componentStore } from "xwiki-livedata";
--
--// Dynamically register a new "toggle" displayer component.
--componentStore.register("displayer", "toggle", async () => {
--  return (await import("./components/DisplayerToggle.vue")).default;
--});
--{{/code}}
--{{/version}}
--
  == LiveTable New Row Naming Strategy ==
--{{version since="18.7.0RC1"}}
--For the live table source, new row creation requires a page naming strategy. For that, there is a specific interface:
++See [[Live Data Extension Points>>xwiki:documentation.xs.dev.livedata.extension-points.WebHome]].
--{{code language="java"}}
--/**
-- * Strategy to generate the document reference of a new livetable entry.
-- *
-- * @since 18.7.0RC1
-- */
--@Role
--@Unstable
--public interface LiveTableNewRowNamingStrategy
--{
--    /**
--     * Generates a document reference for a new livetable entry.
--     *
--     * @param parameters the livedata source parameters
--     * @return the generated document reference
--     * @throws LiveDataException if the reference cannot be generated
--     * @throws XWikiException if there is a wiki-level error
--     */
--    DocumentReference generate(Map<String, Object> parameters) throws LiveDataException, XWikiException;
--
--    /**
--     * Checks if the current user is allowed to create a new entry based on the provided source parameters.
--     *
--     * @param parameters the live data source parameters
--     * @return whether the current user is allowed to create a new entry with this strategy
--     */
--    boolean isCreationAllowed(Map<String, Object> parameters);
--}
--{{/code}}
--
--New strategies can be added by creating new named components implementing this interface, and using their name in a Live Data's ##newRowNamingStrategy## [[source parameter>>||anchor="HParameters-1"]].
--{{/version}}
--
  = Troubleshooting =
++See [[Debug the SQL Query of a Live Data>>xwiki:documentation.xs.dev.livedata.sql-query-debugging.WebHome]].
++
  == Live Table Source ==
--The live table results page used by the ##liveTable## data source supports the ##sql## request parameter that can be used to include in the JSON response the SQL performed on the database and its parameters. This can be useful when debugging problems with the [[Live Table Macro>>Extension.Livetable Macro]], but unfortunately, it can't be used (directly) to debug Live Data problems. You can obtain the same information though from a Live Data instance that uses the ##liveTable## source, with a bit of tweaking:
--
--* First, obtain the URL used to fetch the live data entries, by inspecting the web page and looking at the Network tab from the browser's developer tools. Filter for ##/entries##
--* Open the URL in a new browser tab and add this to the query string: ##&sourceParams.sql=1##
--* Then edit ##XWiki.LiveTableResultsMacros## and look for ##request.sql##
--* Add these two lines:(((
--{{code language="none"}}
--#set ($discard = $services.logging.getLogger('XWiki.LiveTableResultsMacros').debug("SQL: $sql"))
--#set ($discard = $services.logging.getLogger('XWiki.LiveTableResultsMacros').debug("SQL parameters: $sqlParams"))
--{{/code}}
--)))
--* Reload the live data entries URL and then go to the Logging administration section. Search for the "LiveTableResultsMacros" logger and set debug level.
--* Reload again the live data entries URL. The server logs should contain something like this:(((
--{{code langauge="none"}}
--DEBUG X.LiveTableResultsMacros       - SQL:   where 1=1    order by lower(doc.fullName) asc, doc.fullName asc
--DEBUG X.LiveTableResultsMacros       - SQL parameters: {}
--{{/code}}
--)))
++See [[Debug the SQL Query of a Live Data>>xwiki:documentation.xs.dev.livedata.sql-query-debugging.WebHome]].

Website

...	...	@@ -1,0 +1,1 @@
	1	+https://www.xwiki.org/xwiki/bin/view/DocApp/Code/ExtensionLD?id=xwiki:org.xwiki.platform:xwiki-platform-livedata-macro&name=%22Live%20Data%20Macro%22

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.

Point the Live Data Macro page at the new Live Data documentation

All changes

0 outdated Edition of Live Data Macro

Summary

Details

Review this Change Request

Approvers

Ready for review

No conflicts found

Approval strategy

Quick Links

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected