Skip to Content

Ready for review

Live Data documentation migration

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

All changes

Creation of Live Data

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,10 @@
1 +Live Data is a feature provided by the [[Live Data Macro>>doc:extensions:Extension.Live Data Macro.WebHome]] extension. A Live Data instance can display dynamic lists of data from multiple sources, and provides different [[layouts>>doc:documentation.xs.user.livedata.layouts.WebHome]] (table, cards) as well as support for pagination, selection, multi-sort, advanced filtering (through different [[panels>>doc:documentation.xs.user.livedata.panels.WebHome]]) and in-line editing. The Page Index, the index of attachments and the list of orphaned pages are all Live Data instances, which is why they all behave the same way.
2 +
3 +{{image reference="live-data-page-index.png" size="extra" alt="The Page Index of a wiki, displayed as a Live Data table with a pagination bar above the entries and a filter row under the column headers"/}}
4 +
5 +While the document's author controls what is available in the Live Data instance, the reader is free to customize the display on their side. Display changes, which includes the current page of results, the sort, the filters, the visible properties and their order, are stored in the page's URL, meaning that a specific view can be freely shared with others, or bookmarked.
6 +
7 +When the source of the entries supports it and a user is allowed to make changes, values can be [[edited in place>>doc:documentation.xs.user.livedata.edit-value-place.WebHome]] without leaving the page, or in bulk through [[Edit mode>>doc:documentation.xs.user.livedata.edit-mode.WebHome]].
8 +
9 +Any page can display a Live Data, as described in [[Display a List of Data in a Page>>doc:documentation.xs.user.livedata.display-data.WebHome]]. Live Data is the replacement for the older [[live table>>doc:extensions:Extension.Livetable Macro]] feature, which will be removed eventually, so live table users should [[migrate their live tables>>doc:documentation.xs.user.livedata.migrate-live-table.WebHome]].
10 +
live-data-page-index.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +82.6 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Why does the page URL change when I sort or filter? ==
2 +
3 +So that reloading the page or sharing its URL shows the same entries, in the same order, with the same properties visible.
4 +
5 +== Why does this list not offer the Cards layout? ==
6 +
7 +Because the author chose only the layouts they wanted to be available, in the ##layouts## parameter of the Macro.
8 +
9 +== Why can I not change a value I am allowed to edit elsewhere? ==
10 +
11 +Either the source of the entries does not support updating the data, or the author declared that property as non-editable.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data>>doc:documentation.xs.dev.livedata.WebHome]]
2 +* [[Livetable Macro>>doc:extensions:Extension.Livetable Macro]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +explanation
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Creation of Display a List of Data in a Page

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Display a List of Data in a Page
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,12 @@
1 +Display a list of entries in a page with the ##liveData## Macro, described in [[Live Data>>doc:documentation.xs.user.livedata.WebHome]].
2 +
3 +1. Edit the page and write a ##liveData## Macro where the list should appear.(((
4 +{{image reference="live-data-macro-editor.png" size="extra" alt="The wiki editor of a page whose content is a liveData Macro call with its parameters"/}}
5 +)))
6 +1. Set ##source## to the id of the [[Live Data source>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]] providing the entries, and ##sourceParameters## to the query string that source expects.
7 +1. Set ##properties## to the comma-separated ids of the properties to display, in the order they should appear. Leave it out to display every property the source declares.
8 +1. Set the optional ##id##, ##sort##, ##filters##, ##limit## and ##layouts## parameters, listed in [["liveData" Macro>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]].
9 +1. Save the page. The entries are displayed in the first layout of the list, as follows:(((
10 +{{image reference="live-data-page.png" size="extra" alt="A saved wiki page displaying its entries as a Live Data table with a filter row and a pagination bar"/}}
11 +)))
12 +
live-data-macro-editor.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +20.7 KB
Content
live-data-page.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +48.2 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,16 @@
1 +== Where do I find the ids of the properties I can display? ==
2 +
3 +They depend on the source; for the ##liveTable## source they are the properties of the class named in ##className##, plus document properties such as ##doc.title##.
4 +
5 +== What is the ##id## parameter for? ==
6 +
7 +It names the instance. Each Live Data stores its display state in the page URL under that id, and scripts reach it by it, so two instances in one page must not share one. It is optional, and a page holding a single Live Data can do without it.
8 +
9 +== Can I display data that is not stored in the wiki? ==
10 +
11 +Yes, by writing the entries in the Macro content as in-line data.
12 +
13 +== Can I display a Live Data from a Velocity template? ==
14 +
15 +Yes, with the [[Live Data Script Service>>doc:documentation.xs.dev.livedata.script-service.WebHome]], which is the only option where Macros cannot be used.
16 +
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Migrate a Live Table to Live Data>>doc:documentation.xs.user.livedata.migrate-live-table.WebHome]]
2 +* [[Live Data Layouts>>doc:documentation.xs.user.livedata.layouts.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Creation of "liveData" Macro

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +"liveData" Macro
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,16 @@
1 +== Can the Macro be used inside a sentence? ==
2 +
3 +No, it is a block Macro and always starts a new block.
4 +
5 +== A parameter and the Macro content set the same thing. Which one applies? ==
6 +
7 +The Macro parameter, as explained in [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]].
8 +
9 +== What happens if I set no parameter at all? ==
10 +
11 +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.
12 +
13 +== Why are fewer entries displayed than the ##limit## I set? ==
14 +
15 +Because query limits cap the number of entries a page may display, at 1000 by default.
16 +
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]]
2 +* [[Live Data Layouts>>doc:documentation.xs.user.livedata.layouts.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro
DocApp.Code.RenderingMacroClass[0]
Macro Description
... ... @@ -1,0 +1,3 @@
1 +Displays a list of entries fetched from a [[Live Data source>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]], offering different layouts, pagination, entry selection, multi-property sorting, filtering and in-place editing.
2 +
3 +The Macro is a block Macro: a Live Data always starts a new block.
Macro Examples
... ... @@ -1,0 +1,104 @@
1 +== Displaying the Pages Most Recently Changed in a Location ==
2 +
3 +{{code language="none"}}
4 +{{liveData
5 + id="recentPages"
6 + properties="doc.title,doc.location,doc.author,doc.date"
7 + source="liveTable"
8 + sourceParameters="translationPrefix=platform.index."
9 + filters="doc.location=help"
10 + sort="doc.date:desc"
11 + limit="5"
12 +/}}
13 +{{/code}}
14 +
15 +== Listing the Users of the Wiki ==
16 +
17 +{{code language="none"}}
18 +{{liveData
19 + id="users"
20 + properties="_avatar,doc.name,first_name,last_name"
21 + source="liveTable"
22 + sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory."
23 +/}}
24 +{{/code}}
25 +
26 +== Restricting the Entries with an Initial Filter ==
27 +
28 +{{code language="none"}}
29 +{{liveData
30 + id="users"
31 + properties="_avatar,doc.name,first_name,last_name"
32 + source="liveTable"
33 + sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
34 +/}}
35 +{{/code}}
36 +
37 +== Filtering on Several Values of One Property ==
38 +
39 +The ##tags## property is filtered on two values and hidden, listing the pages tagged ##aaa## or ##bbb## without a tag column.
40 +
41 +{{code language="none"}}
42 +{{liveData
43 + id="documents"
44 + properties="doc.title,doc.date,doc.author,_actions,tags"
45 + source="liveTable"
46 + filters="tags=aaa&tags=bbb"
47 + sourceParameters="className=XWiki.TagClass&translationPrefix=platform.index."
48 +}}{
49 + "meta": {
50 + "propertyDescriptors": [
51 + {
52 + "id": "tags",
53 + "visible": false
54 + }
55 + ]
56 + }
57 +}{{/liveData}}
58 +{{/code}}
59 +
60 +== Taking the Entries from a Custom Results Page ==
61 +
62 +{{code language="none"}}
63 +{{liveData
64 + id="wikis"
65 + properties="wikiprettyname,description,owner,doc.creationDate"
66 + source="liveTable"
67 + sourceParameters="resultPage=WikiManager.WikisLiveTableResults&className=XWiki.XWikiServerClass&translationPrefix=platform.wiki.browse."
68 +/}}
69 +{{/code}}
70 +
71 +== Taking the Entries from a Velocity Template ==
72 +
73 +{{code language="none"}}
74 +{{liveData
75 + id="groups"
76 + properties="name,members"
77 + source="liveTable"
78 + sourceParameters="template=getgroups.vm&translationPrefix=xe.admin.groups."
79 +/}}
80 +{{/code}}
81 +
82 +== Choosing the Displayer of One Property ==
83 +
84 +The ##actions## property holds HTML and should be neither sortable nor filterable.
85 +
86 +{{code language="none"}}
87 +{{liveData
88 + id="logging"
89 + properties="logger,level,actions"
90 + source="liveTable"
91 + sourceParameters="resultPage=XWiki.LoggingAdminTableJson&translationPrefix=logging.admin.livetable."
92 +}}{
93 + "meta": {
94 + "propertyDescriptors": [
95 + {
96 + "id": "actions",
97 + "displayer": "html",
98 + "sortable": false,
99 + "filterable": false
100 + }
101 + ]
102 + }
103 +}{{/liveData}}
104 +{{/code}}
Macro Parameters
... ... @@ -1,0 +1,14 @@
1 +|=Name|=Mandatory|=Allowed Values|=Default Value|=Description
2 +|##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.
3 +|##properties##|No|A comma-separated list of property ids|Every property the source declares|The properties to fetch and display, in display order.
4 +|##source##|No|The hint of a Live Data source|N/A|The source providing the entries, specified as a [[component>>doc:extensions:Extension.Component Module]] hint. Without it the entries come from the in-line data in the Macro content.
5 +|##sourceParameters##|No|A URL query string|N/A|The parameters of the source. These are listed for specific sources in [[Live Data Sources>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]].
6 +|##filters##|No|A URL query string of ##property=value## pairs|N/A|The filters applied initially. Repeat a property to filter on several values.
7 +|##sort##|No|Property ids, each optionally suffixed with ##:asc## or ##:desc##|N/A|The properties to sort on initially, in order of precedence.
8 +|##limit##|No|A positive number|##15##|The number of entries per page. [[Query limits>>doc:extensions:Extension.Query Module||anchor="HQueryLimits"]] cap it at 1000 by default.
9 +|##offset##|No|A positive number|##0##|The index of the first entry to show.
10 +|##layouts##|No|A comma-separated list of layout ids|##table,cards##|The [[layouts>>doc:documentation.xs.user.livedata.layouts.WebHome]] the reader may choose from. The first of the list is displayed initially.
11 +|##showPageSizeDropdown##|No|##true## or ##false##|##false##|Whether the reader can change the number of entries per page through a drop-down.
12 +|##pageSizes##|No|A comma-separated list of numbers|##15,25,50,100##|The values offered in that drop-down.
13 +|##description##|No|Any text|N/A|{{version since="16.0.0RC1"}}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.{{/version}}
14 +
Macro Usage
... ... @@ -1,0 +1,16 @@
1 +Every parameter is optional. A call normally names the ##source## the entries come from, its ##sourceParameters##, and the ##properties## to display:
2 +
3 +{{code language="none"}}
4 +{{liveData
5 + id="..."
6 + properties="..."
7 + source="..."
8 + sourceParameters="..."
9 + filters="..."
10 + sort="..."
11 + limit="..."
12 +/}}
13 +{{/code}}
14 +
15 +The Macro content may hold an advanced configuration, written as the JSON document described in [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]]. Where a parameter and that JSON set the same thing, the parameter wins.
16 +

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Sources
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,113 @@
1 +A Live Data source provides both the entries and what the Live Data needs in order to interact with them: which properties exist, which of them can be sorted, filtered or edited, and how each is displayed. The ##source## Macro parameter names one by its [[Component>>doc:extensions:Extension.Component Module]] hint, and ##sourceParameters## carries the query string that source understands.
2 +
3 +|=Source|=Hint|=Entries come from
4 +|Live Table results|##liveTable##|Any [[live table>>doc:extensions:Extension.Livetable Macro]] results page, which makes an existing live table usable as a Live Data
5 +|In-line data|N/A|The Macro content itself, written as JSON
6 +
7 +Implementing a new source is described in [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]].
8 +
9 +== Live Table Source ==
10 +
11 +The ##liveTable## source exposes any live table results page as a Live Data. Adding ##useLiveData=true## to the query string of a page holding a live table previews it as a Live Data without changing the page.
12 +
13 +It accepts these [[live table parameters>>doc:extensions:Extension.Livetable Macro||anchor="HParameter24options"]]:
14 +
15 +|=Name|=Default Value|=Description
16 +|##className##|N/A|The class whose objects are listed. Its properties become the properties of the entries.
17 +|##resultPage##|##XWiki.LiveTableResults##|The page producing the results.
18 +|##queryFilters##|##currentlanguage,hidden##|The [[query filters>>doc:extensions:Extension.Query Module]] applied. With the default value the content is translated to the locale of the reader, and hidden pages are listed only for readers whose profile sets "Display hidden pages" to "Yes".
19 +|##translationPrefix##|N/A|The prefix of the translation keys used for the property names.
20 +|##template##|N/A|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.
21 +|##hasEditMode##|##false##|{{version since="18.7.0RC1"}}Whether the reader may switch the Live Data to [[Edit mode>>doc:documentation.xs.user.livedata.edit-mode.WebHome]].{{/version}}
22 +|##newRowLocation##|N/A|{{version since="18.7.0RC1"}}Location to store pages when creating new rows. Requires a compatible row naming strategy, //e.g.//, ##uuid##.{{/version}}
23 +|##newRowNamingStrategy##|N/A|{{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}}
24 +
25 +The ##extraParams## live table parameter is deliberately unsupported: its main use is filtering, and a Live Data expresses filters generically. [[Migrate a Live Table to Live Data>>doc:documentation.xs.user.livedata.migrate-live-table.WebHome]] says what to do with it. A live table that built its parameters in Velocity, as in:
26 +
27 +{{code language="none"}}
28 +{{velocity}}
29 +#set ($options = {
30 + 'className': 'ExtensionCode.ExtensionVersionClass',
31 + 'location': "${doc.space}"
32 +})
33 +
34 +{{liveData
35 + id="versions"
36 + properties="version,notes"
37 + source="liveTable"
38 + sourceParameters="$services.rendering.escape($escapetool.url($options), 'xwiki/2.1')"
39 +/}}
40 +{{/velocity}}
41 +{{/code}}
42 +
43 +passes them to the source the same way, once URL-encoded and escaped for the wiki syntax.
44 +
45 +=== Properties from Other Classes ===
46 +
47 +{{version since="18.0.0RC1"}}
48 +It is possible to specify a property from another class than the one named in ##className## by passing a ##<property>_class## source parameter, and it can then be filtered, sorted and edited like any other. When a displayed page holds no object of that class yet, one is created the first time the property is saved.
49 +
50 +{{code language="none"}}
51 +{{liveData properties="doc.location,doc.title,tags" source="liveTable" sourceParameters="tags_class=XWiki.TagClass&translationPrefix=platform.index."/}}
52 +{{/code}}
53 +{{/version}}
54 +
55 +== In-line Data ==
56 +
57 +The entries are written directly in the Macro content as JSON, together with the property descriptors saying how to display them. No source is named in that case.
58 +
59 +{{code language="none"}}
60 +{{liveData
61 + id="movies"
62 + properties="title,genre,releaseDate,director"
63 +}}{
64 + "data": {
65 + "count": 2,
66 + "entries": [
67 + {
68 + "title": "Meet John Doe",
69 + "url": "https://www.imdb.com/title/tt0033891/",
70 + "genre": ["Comedy", "Romance"],
71 + "releaseDate": -904615200,
72 + "director": "Frank Capra",
73 + "directorURL": "https://www.imdb.com/name/nm0001008/"
74 + },
75 + {
76 + "title": "Modern Times",
77 + "url": "https://www.imdb.com/title/tt0027977/",
78 + "genre": ["Comedy", "Drama"],
79 + "releaseDate": -1068256800,
80 + "director": "Charlie Chaplin",
81 + "directorURL": "https://www.imdb.com/name/nm0000122/"
82 + }
83 + ]
84 + },
85 + "meta": {
86 + "propertyDescriptors": [
87 + {"id": "title", "name": "Title", "visible": true, "displayer": {"id": "link", "propertyHref": "url"}},
88 + {"id": "genre", "name": "Genre", "visible": true},
89 + {"id": "releaseDate", "name": "Release Date", "visible": true, "displayer": "date"},
90 + {"id": "director", "name": "Director", "visible": true, "displayer": {"id": "link", "propertyHref": "directorURL"}}
91 + ]
92 + }
93 +}{{/liveData}}
94 +{{/code}}
95 +
96 +{{warning}}
97 +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 Bottombar 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:
98 +
99 +{{code language="none"}}
100 +"pagination": {
101 + "showEntryRange": false,
102 + "showNextPrevious": false,
103 + "showFirstLast": false
104 +}
105 +{{/code}}
106 +
107 +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>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]]:
108 +{{code language="css"}}
109 +.livedata-topbar {display: none !important;}
110 +.livedata-bottombar {display: none !important;}
111 +{{/code}}
112 +{{/warning}}
113 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Can a Live Data list entries from another wiki of the farm? ==
2 +
3 +Working around [[XWIKI-22688>>https://jira.xwiki.org/browse/XWIKI-22688]], name the results page with its full reference, as in ##resultPage=xwiki:XWiki.LiveTableResults##, and set the displayers by hand.
4 +
5 +== How do I check what a live table would look like as a Live Data? ==
6 +
7 +Add ##useLiveData=true## to the query string of the page holding it. Nothing is modified.
8 +
9 +== Why are the property names displayed as translation keys? ==
10 +
11 +Because ##translationPrefix## is missing, or does not match the keys declaring the property names.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]]
2 +* [[Migrate a Live Table to Live Data>>doc:documentation.xs.user.livedata.migrate-live-table.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-livetable

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Layouts
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,36 @@
1 +A layout handles how the entries are arranged on screen. A reader can switch freely between the layouts allowed by the author, which can be:
2 +
3 +|=Id|=Name|=Arranges the entries as
4 +|##table##|Table|One row per entry, one column per property
5 +|##cards##|Cards|One card per entry, laid out in a grid
6 +
7 +== Table ==
8 +
9 +One row per entry, one column per property.
10 +
11 +{{image reference="live-data-table.png" size="extra" alt="A Live Data table with sortable column headers and a filter row underneath"/}}
12 +
13 +Sorting and filtering are available from the column headers. Dragging a column header, or pressing the left and right arrow keys while it is focused, moves that property. Columns are resized by dragging the handle that appears between two headers when hovering them; double-clicking that handle, or pressing "Escape" while it is focused, restores the original width.
14 +
15 +{{image reference="live-data-table-responsive.png" size="medium" alt="A Live Data table on a narrow screen, with the properties of an entry stacked vertically"/}}
16 +
17 +On a narrow screen the table reorganizes itself so every property stays available.
18 +
19 +{{image reference="table-no-entries.png" size="extra" alt="A Live Data table whose filter matches nothing, displaying a message stating that no entry was found in the bar under the entries"/}}
20 +
21 +When no entry matches (because the Live Data is empty, or all the entries are filtered out), a "(No entries)" message is displayed in the bar under the entries.
22 +
23 +== Cards ==
24 +
25 +One card per entry, arranged in a grid.
26 +
27 +{{image reference="live-data-cards.png" size="extra" alt="A Live Data displaying its entries as cards arranged in a grid"/}}
28 +
29 +There are no column headers, so sorting and filtering are done from the [[Sort and Filter panels>>doc:documentation.xs.user.livedata.panels.WebHome]]. Inside a card, each property carries a "â‹®" handle that drags it to another position. When no entry matches, the "(No entries)" message is displayed under the cards, as it is in the Table layout.
30 +
31 +== Selection ==
32 +
33 +{{image reference="live-data-table-selection.png" size="extra" alt="A Live Data table whose first column holds selection checkboxes, with two entries ticked"/}}
34 +
35 +When the author enables selection, each entry contains a checkbox that can be ticked for batch actions.
36 +
live-data-cards.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +129.1 KB
Content
live-data-table-responsive.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +25.7 KB
Content
live-data-table-selection.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +74.4 KB
Content
live-data-table.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +121.5 KB
Content
table-entries.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +29.7 KB
Content
table-no-entries.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +14.1 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,12 @@
1 +== How do I switch to another layout? ==
2 +
3 +Open the "More Actions" menu on the right of the Live Data and pick it there. Only the layouts the author listed are offered.
4 +
5 +== Why is the column width I set lost when I come back to the page? ==
6 +
7 +Because column widths are not part of the state stored in the page URL, unlike the sort, the filters and the visible properties.
8 +
9 +== Can I reorder the properties in the Cards layout? ==
10 +
11 +Yes, by dragging the "â‹®" handle of a property inside a card, or from the [[Properties panel>>doc:documentation.xs.user.livedata.panels.WebHome]].
12 +
Related
... ... @@ -1,0 +1,1 @@
1 +* [["liveData" Macro>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Creation of Live Data Panels

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Panels
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,25 @@
1 +The panels are available from the "More Actions" menu, the "â‹®" button on the right of a Live Data. They affect the Live Data no matter which [[layout>>doc:documentation.xs.user.livedata.layouts.WebHome]] is displayed.
2 +
3 +|=Panel|=Acts on
4 +|Properties|Which properties are displayed, and in which order
5 +|Sort|The properties the entries are sorted on
6 +|Filter|The constraints the entries must satisfy
7 +
8 +== Properties Panel ==
9 +
10 +{{image reference="live-data-panel-properties.png" size="large" alt="The Properties panel listing the properties of a Live Data, each with a visibility switch"/}}
11 +
12 +Every property the Live Data knows is listed here and can be toggled on and off. The properties can also be reordered with drag and drop. Each [[layout>>doc:documentation.xs.user.livedata.layouts.WebHome]] offers the same reordering outside the panel: by dragging a column header in the Table layout, or the "â‹®" handle of a property in the Cards layout.
13 +
14 +== Sort Panel ==
15 +
16 +{{image reference="live-data-panel-sort.png" size="large" alt="The Sort panel with two properties stacked, each with an ascending or descending direction"/}}
17 +
18 +The Sort panel allows you to sort on multiple properties, provided the properties are marked as sortable and provided the Live Data source supports sorting (either on single or multiple properties). Note that some layouts, like the Table layout, might have shortcuts for sorting (e.g., click on the column header).
19 +
20 +== Filter Panel ==
21 +
22 +{{image reference="live-data-panel-filter.png" size="large" alt="The Filter panel with a property, a constraint operator and a value"/}}
23 +
24 +The Filter panel allows you to filter on multiple properties. For each property you can add multiple constraints, provided the property is declared as filterable (as indicated by the live data configuration). The widget used to enter a value depends on the type of the property and on the constraint operator. The following filter widgets are currently supported: text field, number field, suggestion list, date picker, checkbox.
25 +
live-data-panel-filter.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +12.2 KB
Content
live-data-panel-properties.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +13.1 KB
Content
live-data-panel-sort.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +8.1 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,8 @@
1 +== Why is one of my properties missing from the Sort or Filter panel? ==
2 +
3 +Because the source declared it as not sortable, or not filterable. That is decided by the Live Data configuration, not by the reader.
4 +
5 +== Are the panels available in every layout? ==
6 +
7 +Yes. The Table layout additionally offers shortcuts in its header, but the panels are always reachable from the "More Actions" menu.
8 +
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Creation of Edit a Value in Place

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Edit a Value in Place
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,12 @@
1 +Change one value of a [[Live Data>>doc:documentation.xs.user.livedata.WebHome]] without leaving the page.
2 +
3 +1. Hover the value to change, or touch it on a touch-based device, to make the popover holding the edit action button appear.(((
4 +{{image reference="edit-value-popover.png" size="medium" alt="A Live Data cell being hovered, with a popover holding an edit action button above it"/}}
5 +)))
6 +1. Click the edit action button, which replaces the value by a form.(((
7 +{{image reference="edit-value-form.png" size="medium" alt="A Live Data cell whose value has been replaced by an edit form"/}}
8 +)))
9 +1. Change the value in the form.
10 +1. Click outside the form. The Live Data reloads and displays the new value, as follows:(((
11 +{{image reference="edit-value-saved.png" size="medium" alt="The Live Data cell displaying its new value after the change was saved"/}}
12 +)))
edit-value-form.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +3.8 KB
Content
edit-value-popover.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +6.1 KB
Content
edit-value-saved.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +6.4 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== How do I abandon a change I started? ==
2 +
3 +Press "Escape". The form closes and the value is displayed unchanged.
4 +
5 +== Why does no edit button appear when I hover a value? ==
6 +
7 +Either the source does not support updating the data, the property was declared as not editable, or you may not edit that entry.
8 +
9 +== The popover appeared when I only wanted to follow a link. What happened? ==
10 +
11 +On a touch-based device, touching a link inside a property opens the popover, which then offers both the edit action and one following the link.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Edit Several Entries at Once>>doc:documentation.xs.user.livedata.edit-mode.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Edit Several Entries at Once
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,22 @@
1 +{{version since="18.7.0RC1"}}
2 +Edit mode helps with bulk editing: it displays every hidden column, and turns a single click on a cell into an edit. A [[Live Data>>doc:documentation.xs.user.livedata.WebHome]] offers it only when the source of its entries supports it, which for the [[Live Table source>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]] means the author set ##hasEditMode## to ##true##.
3 +
4 +== Change the Values of Several Entries ==
5 +
6 +1. Click the Edit mode toggle in the Live Data menu.(((
7 +{{image reference="live-data-edit-mode-toggle.png" size="medium" alt="The Edit mode toggle in the menu of a Live Data"/}}
8 +)))
9 +1. Click the cell to change and set its new value.
10 +1. Press "Tab" to save that cell and open the next one, or "Shift+Tab" for the previous one, until every value is set. Each cell is saved as it is left, so there is nothing else to confirm.
11 +
12 +== Create an Entry ==
13 +
14 +1. Click "Add entry" in the row at the bottom of the table.(((
15 +{{image reference="live-data-add-entry.png" size="extra" alt="The Add entry row at the bottom of a Live Data in Edit mode, under the last entry"/}}
16 +)))
17 +1. Fill the cells of the draft entry, moving between them with the mouse or with "Tab".(((
18 +{{image reference="live-data-row-draft.png" size="large" alt="A draft entry at the bottom of a Live Data, with the validate and cancel action buttons on its right"/}}
19 +)))
20 +1. Click the "✓" button on the right of the draft entry, or press "Return", to save it. The draft row is replaced by a normal entry of the Live Data.
21 +{{/version}}
22 +
live-data-add-entry.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +5.8 KB
Content
live-data-edit-mode-toggle.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +23.0 KB
Content
live-data-row-draft.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +21.8 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,20 @@
1 +== Why is there no Edit mode toggle on my Live Data? ==
2 +
3 +Because the source of its entries does not support Edit mode. The Live Table source does, but only when the author sets its ##hasEditMode## parameter to ##true##.
4 +
5 +== Why is there no "Add entry" row? ==
6 +
7 +Because the source does not support creating entries, or you do not have the right to create content where they would be stored.
8 +
9 +== How do I discard a draft entry? ==
10 +
11 +Click the "✗" button on its right. The draft entry is deleted and nothing is saved.
12 +
13 +== How do I save an entry and immediately start another? ==
14 +
15 +Press "Ctrl+Return" instead of "Return".
16 +
17 +== Where are the entries I create stored? ==
18 +
19 +Where the source decides. The Live Table source stores them under its ##newRowLocation## parameter, with names produced by its ##newRowNamingStrategy## one.
20 +
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Edit a Value in Place>>doc:documentation.xs.user.livedata.edit-value-place.WebHome]]
2 +* [[Live Data Sources>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Migrate a Live Table to Live Data
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,15 @@
1 +Replace a live table instance by a [[Live Data>>doc:documentation.xs.user.livedata.WebHome]], reusing the results page the live table already reads.
2 +
3 +1. Open the page holding the live table, to see the list it displays before changing anything.(((
4 +{{image reference="live-table-before.png" size="extra" alt="A page displaying its entries as a live table, with a results count above the column headers and a filter row under them"/}}
5 +)))
6 +1. Add ##useLiveData=true## to the query string of that URL, to see the same live table rendered as a Live Data without touching the page.
7 +1. Replace the ##livetable## Macro call by a ##liveData## Macro call whose ##source## is ##liveTable##, moving ##className##, ##resultPage##, ##queryFilters## and ##translationPrefix## into the ##sourceParameters## query string, and the columns into ##properties##.
8 +1. Set ##template## instead of ##resultPage## if the results came from a Velocity template, named in the ##xpage## query string of the live table ##url## configuration.
9 +1. Convert the ##extraParams## entries used for filtering into the ##filters## Macro parameter, and move the rest into ##sourceParameters##.
10 +1. Save the page and check every converted filter. The list is displayed as a Live Data, as follows:(((
11 +{{image reference="migrated-live-data.png" size="extra" alt="The same list after the migration, displayed as a Live Data by a liveData Macro"/}}
12 +)))
13 +
14 +The results page itself needs no change, which is what makes the migration a rewrite of the Macro call only. The filters are worth checking one by one because a source parameter passed straight through is not guaranteed to have the same effect on a Live Data as it had on a live table.
15 +
live-table-before.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +24.0 KB
Content
live-table-live-data.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.pjeanjean
Size
... ... @@ -1,0 +1,1 @@
1 +39.0 KB
Content
migrated-live-data.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +24.5 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Why is ##extraParams## not supported as such? ==
2 +
3 +Because its main use is filtering, and a Live Data expresses filters generically through the ##filters## Macro parameter, which every source honours.
4 +
5 +== Do I have to rewrite my live table results page? ==
6 +
7 +No. The ##liveTable## source reads it as it is, which is what makes the migration a rewrite of the Macro call only.
8 +
9 +== A property was rendered differently by the live table. How do I get the same rendering? ==
10 +
11 +By setting the displayer of that property in the Macro content, as described in [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]].
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data Sources>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]]
2 +* [[Livetable Macro>>doc:extensions:Extension.Livetable Macro]]
Target
... ... @@ -1,0 +1,1 @@
1 +user
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Edition of Live Data

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.mleduc
1 +XWiki.elenicojocariu
Content
... ... @@ -1,2 +1,37 @@
1 -Live Data (LD) allows displaying structured data in a user-friendly and customizable way. LD also allow users to interact with the presented content and to edit it.
2 -From a developer standpoint, LD provides APIs to define custom data sources, or to configure existing ones.
1 +Live Data is a feature provided by the [[Live Data Macro>>doc:extensions:Extension.Live Data Macro.WebHome]] extension. It displays structured data in a customizable way, and it provides APIs to define custom data sources as well as to configure the existing ones.
2 +
3 +A Live Data instance is built in two parts, which meet in a JSON document. On the server, the [["liveData" Macro>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]] or the [[Script Service>>doc:documentation.xs.dev.livedata.script-service.WebHome]] turns its parameters and the advanced configuration written in the Macro content into a complete [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]]. In the browser, a Vue widget reads that configuration and renders the entries using the layout, the displayers and the filters it names, fetching the entries themselves over REST.
4 +
5 +{{plantuml}}
6 +@startuml
7 +!theme bluegray
8 +skinparam componentStyle rectangle
9 +
10 +component "**liveData Macro**\nLiveDataMacro" as MACRO
11 +component "**LiveDataScriptService**\n$services.liveData" as SS
12 +component "**LiveDataRenderer**\nmerges parameters and content" as REND
13 +component "**LiveDataConfigurationResolver**\nadds the default values" as RES
14 +component "**Live Data widget**\nVue, in the browser" as VUE
15 +component "**Live Data REST resources**\nLiveDataEntriesResource\nLiveDataPropertiesResource" as REST
16 +component "**LiveDataSource**\nlooked up under the source hint" as SRC
17 +component "**LiveDataEntryStore**\nget, save, update, remove" as ES
18 +component "**LiveDataPropertyDescriptorStore**\nwhich properties exist" as PS
19 +database "The entries\nwiki objects, or anything else" as DATA
20 +
21 +MACRO --> REND
22 +SS --> REND
23 +REND --> RES : resolves the merged configuration
24 +REND --> VUE : writes the JSON configuration in the page
25 +VUE --> REST : queries entries and properties
26 +REST --> SRC
27 +SRC --> ES
28 +SRC --> PS
29 +ES --> DATA
30 +PS ..> DATA : describes
31 +@enduml
32 +{{/plantuml}}
33 +
34 +Everything the widget knows about the data comes from its source, which is looked up as a [[Component>>doc:extensions:Extension.Component Module]] under the hint given in the ##source## Macro parameter. A source answers two questions, through two stores: which entries match a query, and which properties those entries have (including whether each one can be sorted, filtered or edited). A source that implements none of the writing operations simply yields a Live Data the reader can browse but not change.
35 +
36 +The front-end is extended the same way: layouts, displayers, filters and panels are registered by name, and picked up by the configuration that names them. All the roles, on both sides, are listed in [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]]. The widget itself ships as a webjar, described in [[Live Data Webjar API>>doc:documentation.xs.dev.livedata.webjar.WebHome]], and exposes a [[JavaScript API>>doc:documentation.xs.dev.livedata.javascript-api.WebHome]] on the container of each instance. When a Live Data returns the wrong entries, it can be [[debugged by reading its query from the logs>>doc:documentation.xs.dev.livedata.sql-query-debugging.WebHome]].
37 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,12 @@
1 +== Do I have to write Java to add a Live Data source? ==
2 +
3 +Yes for the source itself, which is a Java Component; the ##liveTable## source often avoids it, since it turns any live table results page into a source.
4 +
5 +== How do I make a Live Data read-only? ==
6 +
7 +By leaving ##save## and ##remove## out of the ##LiveDataEntryStore## implementation: their default implementations throw ##UnsupportedOperationException##.
8 +
9 +== Where does configuration that no Macro parameter covers go? ==
10 +
11 +In the Macro content, as JSON, described in [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]].
12 +
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data>>doc:documentation.xs.user.livedata.WebHome]]
2 +* [[Component Module>>doc:extensions:Extension.Component Module]]
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Creation of Live Data Configuration

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Configuration
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,328 @@
1 +Every Live Data instance is described by one JSON document. The [["liveData" Macro>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]] and the [[Script Service>>doc:documentation.xs.dev.livedata.script-service.WebHome]] build part of it from their parameters, merge the JSON written in the Macro content into it and add the default values. Macro parameters win when both set the same property.
2 +
3 +It has three parts:
4 +* ##query##, what to fetch
5 +* ##data##, what was fetched
6 +* ##meta##, how to interact with it
7 +
8 +{{code language="javascript"}}
9 +{
10 + //
11 + // The query
12 + //
13 +
14 + "query": {
15 + // The list of properties to fetch.
16 + "properties": ["title", "year", ...],
17 +
18 + "source": {
19 + // The component hint of the live data source
20 + "id": "...",
21 +
22 + // 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.
23 + "customParam1": "...",
24 + ...
25 + },
26 +
27 + // Filter the live data entries.
28 + "filters": [
29 + {
30 + "property": "title",
31 + "matchAll": true,
32 + "constraints": [
33 + {"operator": "contains", "value": "help"},
34 + ],
35 + },
36 + ],
37 +
38 + // The list of properties to sort on.
39 + "sort": [
40 + {
41 + "property": "birthdate",
42 + "descending": false
43 + },
44 + ],
45 +
46 + // Indicates where the current page starts.
47 + "offset": 0,
48 +
49 + // The number of entries to fetch (the page size).
50 + "limit": 10
51 + },
52 +
53 + //
54 + // The data
55 + //
56 +
57 + "data": {
58 + // The total number of entries available (on the server side).
59 + "count": 54,
60 +
61 + "entries": [
62 + {
63 + // property: value
64 + "title": "Work from home",
65 + "year": 2020,
66 + ...
67 + },
68 + ...
69 + ],
70 + },
71 +
72 + //
73 + // The meta data (used to control how we interact with the data)
74 + //
75 +
76 + "meta": {
77 + "defaultLayout": "table",
78 +
79 + "layouts": [
80 + {
81 + "id": "table",
82 + "name": "Table",
83 + "icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-table"},
84 + },
85 + {
86 + "id": "cards",
87 + "name": "Cards",
88 + "icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-th"},
89 + "titleProperty": "doc_title",
90 + },
91 + ],
92 +
93 + // Describes the properties that may appear in the data set. This determines the list of known (available)
94 + // properties. Creating new properties, removing existing properties as well as editing the property descriptor
95 + // should be done through this array.
96 + "propertyDescriptors": [
97 + {
98 + // Identifies the property that this descriptor corresponds to.
99 + "id": "title",
100 +
101 + // The property name. Could be displayed before the property value.
102 + "name": "Title",
103 +
104 + // Could be displayed when hovering the property name.
105 + "description": "...",
106 +
107 + // Could be displayed before the property name, if specified.
108 + "icon": {...},
109 +
110 + // The property type, selected when creating the property. It is used to prefill the property descriptor.
111 + // Could be mapped to an xclass property type.
112 + "type": "String",
113 +
114 + // Whether the user can sort on this property or not.
115 + "sortable": true,
116 +
117 + // 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).
118 + "editable": true,
119 +
120 + // Whether to show this property or not.
121 + "visible": true,
122 +
123 + // Displayer configuration.
124 + "displayer": {
125 + "id": "link",
126 +
127 + // Indicates the property whose value is the URL that should be used as the link target (e.g. 'doc.url').
128 + "propertyHref": "...",
129 +
130 + // Whether to allow HTML in the link content, used by the 'link' displayer
131 + "html": true
132 + },
133 +
134 + // Whether the user can filter by this property or not.
135 + "filterable": true,
136 +
137 + // Filter configuration.
138 + "filter": {
139 + "id": "text",
140 +
141 + // This is used only by the 'text' filter (which receives the property descriptor).
142 + "match": "prefix"
143 + },
144 +
145 + // Optional CSS class name to add to the HTML element used to display this property.
146 + "styleName": "..."
147 + }
148 + ],
149 +
150 + // The list of known property types. When creating a new property the user can select from this list and the
151 + // property descriptor will be prefilled based on the selected property type.
152 + "propertyTypes": [
153 + {"id": "string", "name": "String", "icon": {...}, "sortable": true, "displayer": {...}, "filterable": true, "filter": {...}},
154 + ...
155 + ],
156 +
157 + "defaultFilter": "text",
158 +
159 + // The list of known filters to choose from when editing the property descriptor.
160 + "filters": [
161 + {"id": "text", ...},
162 + {"id": "date", ...},
163 + {"id": "list", ...},
164 + {"id": "number", ...},
165 + {"id": "boolean", ...},
166 + ...
167 + ],
168 +
169 + // The list of known property displayers to choose from when editing the property descriptor.
170 + "displayers": [
171 + {"id": "text", ...},
172 + {"id": "html", ...},
173 + {"id": "link", ...},
174 + {"id": "actions", ...},
175 + {"id": "date", ...},
176 + {"id": "boolean", ...},
177 + {"id": "number", ...},
178 + {"id": "docTitle", ...},
179 + {"id": "xObjectProperty", ...},
180 + ...
181 + ],
182 +
183 + "defaultDisplayer": "text",
184 +
185 + // Configure the pagination display.
186 + "pagination": {
187 + // The maximum number of page links to display in the pagination.
188 + "maxShownPages": 10,
189 + "pageSizes": [15, 25, 50, 100],
190 + "showEntryRange": true,
191 + "showNextPrevious": true,
192 + "showFirstLast": false,
193 + "showPageSizeDropdown": false
194 + },
195 +
196 + "entryDescriptor": {
197 + // The property that can be used to identify a live data entry. This is used for entry selection.
198 + "idProperty": "doc.fullName",
199 + },
200 +
201 + // The list of actions known / supported by this live data instance. This is used by the actions displayer.
202 + "actions": [
203 + {
204 + "id": "view",
205 + "name": "View",
206 + "description": "View entry",
207 + "icon": {...},
208 + "allowProperty": "doc.viewable",
209 + "urlProperty": "doc.url"
210 + },
211 + // Specify the edit action with an allowProperty to control who can in-place edit the entries
212 + // By default, the action is allowed.
213 + {
214 + "id": "edit",
215 + "allowProperty": "doc.editable"
216 + }
217 + ...
218 + ],
219 +
220 + // Selection configuration.
221 + "selection": {
222 + // Whether to enable or not the entry selection (e.g. for batch actions).
223 + "enabled": false
224 + }
225 + }
226 +}
227 +{{/code}}
228 +
229 +== Actions ==
230 +
231 +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.
232 +The example below declares an action ##A## whose allow property is ##allowA##.
233 +
234 +{{code language="json"}}
235 +{
236 + "data": {
237 + "count": 2,
238 + "entries": [
239 + {
240 + "title": "Allowed Entry",
241 + "allowA": true
242 + },
243 + {
244 + "title": "Disallowed Entry",
245 + "allowA": false
246 + }
247 + ]
248 + },
249 + "meta": {
250 + "propertyDescriptors": [
251 + {
252 + "id": "title",
253 + "type": "String"
254 + },
255 + {
256 + "id": "allowA",
257 + "type": "Boolean"
258 + },
259 + {
260 + "id": "_actions",
261 + "name": "_actions",
262 + "visible": true,
263 + "displayer": { "id": "actions", "actions": ["actionA"] }
264 + }
265 + ],
266 + "entryDescriptor": {
267 + "idProperty": "title"
268 + },
269 + "actions": [
270 + {
271 + "id": "actionA",
272 + "name": "Action A",
273 + "description": "Perform action A",
274 + "allowProperty": "allowA"
275 + }
276 + ]
277 + }
278 +}
279 +{{/code}}
280 +
281 +=== Asynchronous Actions ===
282 +
283 +An action can be declared 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.
284 +
285 +==== Parameters ====
286 +
287 +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.
288 +
289 +* ##httpMethod##: the HTTP method to use to call the action URL
290 +* ##loadingMessage##: the localized message to display while the action is running asynchronously
291 +* ##successMessage##: the localized message to display once the action finished successfully
292 +* ##failureMessage##: the localized message to display once the action finished unsuccessfully
293 +* ##body##: (optional) a value to use in the request body
294 +* ##headers## (optional) a map of headers to use for the request
295 +
296 +==== Example ====
297 +
298 +{{code language="none"}}
299 +{{liveData
300 + id="test"
301 + properties="name,_actions"
302 + source="liveTable" sourceParameters="className=Space.MyClass"
303 +}}{
304 + "meta": {
305 + "actions": [{
306 + "id": "delete",
307 + "async": {
308 + "httpMethod": "POST",
309 + "loadingMessage": "Loading",
310 + "successMessage": "Delete Success",
311 + "failureMessage": "Failed",
312 + "body": "newBacklinkTarget=&updateLinks=false&autoRedirect=false&form_token=${services.csrf.token}&confirm=1&async=true",
313 + "headers": {
314 + "Content-Type": "application/x-www-form-urlencoded"
315 + }
316 + }
317 + }]
318 + }
319 +}
320 +{{/liveData}}
321 +{{/code}}
322 +
323 +=== Colored Icons ===
324 +
325 +It 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.
326 +
327 +On the example below, we add the ##text-danger## class on the ##delete## action, making the delete action icon displayed in the danger color (i.e., red by default).
328 +{{code language="none"}}{"id": "delete", "icon": "cross", "extraIconClasses": "text-danger"}{{/code}}
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,15 @@
1 +== Which wins, a Macro parameter or the same property in the Macro content? ==
2 +
3 +The Macro parameter: the two configurations are merged and the one built from the parameters takes precedence.
4 +
5 +== How do I hide an action from some entries only? ==
6 +
7 +By naming a Boolean property of the entry in the ##allowProperty## field of the action descriptor.
8 +
9 +== How do I see the configuration actually applied? ==
10 +
11 +By calling ##effectiveConfig## on the [[Script Service>>doc:documentation.xs.dev.livedata.script-service.WebHome]], which normalises a configuration and fills in the defaults.
12 +
13 +== Can a source parameter act as a filter the reader cannot remove? ==
14 +
15 +Yes. Parameters under ##query.source## are passed to the source and never surfaced in the Filter panel.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +developer
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-api

Creation of Live Data Extension Points

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Extension Points
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,142 @@
1 +Live Data extends on both sides of its JSON configuration: on the server by contributing a [[Component>>doc:extensions:Extension.Component Module]], in the browser by registering a component on the widget. A configuration naming the new hint is enough to reach it.
2 +
3 +|=Extension point|=Kind|=Looked up under|=Contributes
4 +|##LiveDataSource##|Java Component|The value of the ##source## Macro parameter|A new origin for the entries and the property descriptors
5 +|##LiveTableNewRowNamingStrategy##|Java Component|The value of the ##newRowNamingStrategy## source parameter|A way of naming the pages created for new entries by the Live Table source
6 +|##registerPanel##|JavaScript|N/A|A new panel in the Live Data menu
7 +|##componentStore.register##|JavaScript|A kind and a name|A new displayer, filter or layout
8 +
9 +== Adding a Source ==
10 +
11 +A source is what puts a set of entries within reach of page authors: register a Component under a hint, and that hint becomes a value they can pass as the ##source## Macro parameter. The Component itself is small, and hands the real work to two stores.
12 +
13 +{{code language="java"}}
14 +@Role
15 +public interface LiveDataSource
16 +{
17 + LiveDataEntryStore getEntries();
18 +
19 + LiveDataPropertyDescriptorStore getProperties();
20 +}
21 +{{/code}}
22 +
23 +=== Reading and Writing the Entries ===
24 +
25 +##LiveDataEntryStore## is where the data comes from. Only the two read methods have to be written; every other method has a default implementation, and the two that make the Live Data writable throw ##UnsupportedOperationException## by default. A store that keeps those defaults gives a Live Data the reader can browse but not change. Each method also throws ##LiveDataException##.
26 +
27 +|=Method|=Returns|=Write it
28 +|##get(LiveDataQuery)##|The entries matching the query, and how many there are in total|Always
29 +|##get(Object entryId)##|One entry, by its id|Always
30 +|##get(Object entryId, String property)##|One value of one entry|Only to avoid fetching the whole entry, which is what the default does
31 +|##save(Map)##|The id of the entry that was stored|To let the reader create entries, and to let them [[edit values in place>>doc:documentation.xs.user.livedata.edit-value-place.WebHome]], which the default ##update## goes through
32 +|##update(Object, String, Object)##|The value the property had before|Only to replace the default, which reads the entry, sets the property and saves it
33 +|##remove(Object entryId)##|The entry that was removed|To let the reader delete entries
34 +
35 +=== Declaring the Properties ===
36 +
37 +##LiveDataPropertyDescriptorStore## decides what the widget knows about each property: its type, whether it can be sorted, filtered or edited, and which displayer and filter it uses. What this store returns becomes the ##meta.propertyDescriptors## of the [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]], so it is what a reader sees in the [[Properties, Sort and Filter panels>>doc:documentation.xs.user.livedata.panels.WebHome]].
38 +
39 +|=Method|=Returns|=Write it
40 +|##get()##|Every property the entries may have|Always
41 +|##get(String propertyId)##|One descriptor|Only to replace the default, which picks it out of the list above
42 +|##save(LiveDataPropertyDescriptor)##|Whether the descriptor was stored|To let properties be redefined at runtime
43 +|##remove(String propertyId)##|The descriptor that was removed|To let properties be dropped at runtime
44 +
45 +== Naming the Pages Created for New Entries ==
46 +
47 +{{version since="18.7.0RC1"}}
48 +For the live table source, new row creation requires a page naming strategy. For that, there is a specific interface:
49 +
50 +{{code language="java"}}
51 +/**
52 + * Strategy to generate the document reference of a new livetable entry.
53 + *
54 + * @since 18.7.0RC1
55 + */
56 +@Role
57 +@Unstable
58 +public interface LiveTableNewRowNamingStrategy
59 +{
60 + /**
61 + * Generates a document reference for a new livetable entry.
62 + *
63 + * @param parameters the livedata source parameters
64 + * @return the generated document reference
65 + * @throws LiveDataException if the reference cannot be generated
66 + * @throws XWikiException if there is a wiki-level error
67 + */
68 + DocumentReference generate(Map<String, Object> parameters) throws LiveDataException, XWikiException;
69 +
70 + /**
71 + * Checks if the current user is allowed to create a new entry based on the provided source parameters.
72 + *
73 + * @param parameters the live data source parameters
74 + * @return whether the current user is allowed to create a new entry with this strategy
75 + */
76 + boolean isCreationAllowed(Map<String, Object> parameters);
77 +}
78 +{{/code}}
79 +
80 +New strategies can be added by creating new named components implementing this interface, and naming them in the ##newRowNamingStrategy## source parameter of a Live Data.
81 +{{/version}}
82 +
83 +== Adding a Panel ==
84 +
85 +A panel is registered on an instance with ##registerPanel##, from a listener of the ##xwiki:livedata:instanceCreated## event. The reader then toggles it from the Live Data menu, like the built-in panels. This registers a "Hello World" panel:
86 +
87 +{{code language="js"}}
88 +document.addEventListener('xwiki:livedata:instanceCreated', function(e) {
89 + const panel = {
90 + id: 'myExtension',
91 + name: 'My Extension',
92 + title: 'Hello World',
93 + icon: 'camera',
94 + container: document.createElement('div'),
95 + component: 'LiveDataAdvancedPanelExtension',
96 + order: 4000
97 + };
98 +
99 + panel.container.textContent = 'Hello World!';
100 +
101 + e.detail.livedata.registerPanel(panel);
102 +});
103 +{{/code}}
104 +
105 +|=Property|=What it holds
106 +|##id##|A name unique among all the panels of the instance
107 +|##name##|The text displayed in the Live Data menu
108 +|##title##|The text displayed in the title of the panel
109 +|##icon##|The icon displayed both in the menu and in the panel title
110 +|##order##|The display order of the panel. The built-in Properties, Sort and Filter panels are at 1000, 2000 and 3000
111 +|##container##|A DOM node, attached to the panel body while the panel is open and detached when it is collapsed
112 +|##component##|The Vue component rendering the panel. Use ##LiveDataAdvancedPanelExtension##, the only supported one
113 +
114 +Every property must be set when the panel is registered. All of them except ##order## can be changed afterwards, and the change is reflected in the interface, which is how a counter in the name or the title is kept up to date.
115 +
116 +== Registering a Displayer, a Filter or a Layout ==
117 +
118 +Vue 3 no longer allows loading a component globally with ##Vue.component##. Live Data provides a component store instead, on which displayers, filters and layouts are registered by name.
119 +
120 +##componentStore.register(string, string, () => Promise<VueComponent>)##
121 +
122 +* **kind: string**: any of ##filter##, ##layout##, or ##displayer##, defines the type of loaded component
123 +* **name: string**: the name of the registered component
124 +* **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)
125 +
126 +##componentStore.load(string, string): Promise<VueComponent>##
127 +
128 +* **kind: string**: the kind of component to load
129 +* **name: string**: the name of the component to load
130 +* **returns**: a Promise resolving to the component. When nothing is registered under that kind and name yet, the Promise stays pending and is resolved as soon as a matching component is registered
131 +
132 +The store is imported from the ##@xwiki/platform-livedata-componentstore## module, mapped in the [[importmap>>doc:documentation.xs.dev.livedata.webjar.WebHome]] of the Live Data webjar:
133 +
134 +{{code language="javascript"}}
135 +import { componentStore } from "@xwiki/platform-livedata-componentstore";
136 +
137 +// Dynamically register a new "toggle" displayer component.
138 +componentStore.register("displayer", "toggle", async () => {
139 + return (await import("./components/DisplayerToggle.vue")).default;
140 +});
141 +{{/code}}
142 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,16 @@
1 +== Do I have to implement writing to add a source? ==
2 +
3 +No. ##save## and ##remove## have default implementations throwing ##UnsupportedOperationException##, giving a read-only Live Data.
4 +
5 +== Can a source be written in a wiki page? ==
6 +
7 +No, a source is a Java Component; the ##liveTable## source is the way round it, turning any live table results page into a source.
8 +
9 +== Is the panel component API stable? ==
10 +
11 +Only ##LiveDataAdvancedPanelExtension## is. Any other Vue component may be affected by a future change of the widget's internals.
12 +
13 +== My displayer is never displayed. What happened? ==
14 +
15 +Most likely it was registered under a different kind or name than the configuration asks for. ##load## does not fail in that case: it returns a Promise that stays pending until something is registered under the name it was asked for.
16 +
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data Webjar API>>doc:documentation.xs.dev.livedata.webjar.WebHome]]
2 +* [[Live Data JavaScript API>>doc:documentation.xs.dev.livedata.javascript-api.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +developer
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-api

Creation of Live Data Script Service

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data Script Service
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,91 @@
1 +The ##liveData## Script Service renders a Live Data, and runs Live Data queries, from a script. It is the only way to display one where Macros cannot be used, in ##.vm## templates in particular. Prefer the [["liveData" Macro>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]] whenever it can be used.
2 +
3 +Every method throws ##LiveDataException## when the Live Data cannot be run.
4 +
5 +|=Member|=Returns|=What it does
6 +|##query(Map queryConfig)##, ##query(String queryConfigJSON)##|A ##LiveData##|Runs a Live Data query and returns the entries matching it, without displaying anything
7 +|##effectiveConfig(Map liveDataConfig)##, ##effectiveConfig(String liveDataConfigJSON)##|The configuration, in the shape the argument was given in|Normalizes a [[configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]] into the format the widget expects and fills in the missing default values
8 +|##execute(Map parameters)##, ##execute(Map parameters, Map advancedParameters)##|A rendering ##Block##|{{version since="16.0.0RC1"}}Builds the Live Data and returns it as a ##Block##, for code that goes on to manipulate it{{/version}}
9 +|##render(Map parameters)##, ##render(Map parameters, Map advancedParameters)##|A ##String##|{{version since="16.0.0RC1"}}Builds the Live Data and returns it rendered in the current syntax{{/version}}
10 +
11 +##parameters## holds the same entries as the [[Macro parameters>>doc:documentation.xs.user.livedata.display-data.macro.WebHome]], and ##advancedParameters## plays the part the Macro content plays for the Macro.
12 +
13 +== Examples ==
14 +
15 +This script:
16 +
17 +{{code language="none"}}
18 +{{velocity}}
19 + #set($properties = {
20 + "id" : "users",
21 + "properties" : "_avatar,doc.name,first_name,last_name",
22 + "source" : "liveTable",
23 + "sourceParameters" : "className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
24 + })
25 + {{html}}
26 + $services.liveData.render($properties)
27 + {{/html}}
28 +{{/velocity}}
29 +{{/code}}
30 +
31 +is equivalent to:
32 +
33 +{{code language="none"}}
34 +{{liveData
35 + id="users"
36 + properties="_avatar,doc.name,first_name,last_name"
37 + source="liveTable"
38 + sourceParameters="className=XWiki.XWikiUsers&translationPrefix=xe.userdirectory.&last_name=Doe"
39 +/}}
40 +{{/code}}
41 +
42 +And, with an advanced configuration:
43 +
44 +{{code language="none"}}
45 +{{velocity}}
46 + #set($properties = {
47 + "id" : "logging",
48 + "properties" : "logger,level,actions",
49 + "source" : "liveTable",
50 + "sourceParameters" : "resultPage=XWiki.LoggingAdminTableJson&translationPrefix=logging.admin.livetable."
51 + })
52 + #set($advancedProperties = {
53 + "meta": {
54 + "propertyDescriptors": [
55 + {
56 + "id": "actions",
57 + "displayer": "html",
58 + "sortable": false,
59 + "filterable": false
60 + }
61 + ]
62 + }
63 + })
64 + {{html}}
65 + $services.liveData.render($properties, $advancedProperties)
66 + {{/html}}
67 +{{/velocity}}
68 +{{/code}}
69 +
70 +is equivalent to:
71 +
72 +{{code language="none"}}
73 +{{liveData
74 + id="logging"
75 + properties="logger,level,actions"
76 + source="liveTable"
77 + sourceParameters="resultPage=XWiki.LoggingAdminTableJson&translationPrefix=logging.admin.livetable."
78 +}}{
79 + "meta": {
80 + "propertyDescriptors": [
81 + {
82 + "id": "actions",
83 + "displayer": "html",
84 + "sortable": false,
85 + "filterable": false
86 + }
87 + ]
88 + }
89 +}{{/liveData}}
90 +{{/code}}
91 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,15 @@
1 +== Which method displays a Live Data? ==
2 +
3 +##render##, whose result is the Live Data in the current syntax; ##execute## returns the rendering ##Block## instead, for code going on to manipulate it.
4 +
5 +== How do I pass the advanced configuration? ==
6 +
7 +As the second argument of ##render## or ##execute##, which plays the part the Macro content plays for the Macro.
8 +
9 +== How do I inspect the configuration that will be applied? ==
10 +
11 +By calling ##effectiveConfig##, which normalises a configuration and adds the missing default values.
12 +
13 +== Can I fetch the entries without displaying them? ==
14 +
15 +Yes, with ##query##, which runs a Live Data query and returns the matching entries.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Live Data Configuration>>doc:documentation.xs.dev.livedata.configuration.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +developer
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-api

Creation of Live Data JavaScript API

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Live Data JavaScript API
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,24 @@
1 +Live Data provides a JavaScript API on the container of each instance, reached through the ##liveData## jQuery data-property (as in ##jQuery("#wikis").data("liveData")##) and in [[Live Data events>>xwiki:Documentation.DevGuide.FrontendResources.JavaScriptAPI.WebHome||anchor="HLiveDataevents28Logic.js29"]].
2 +
3 +== Methods ==
4 +
5 +|=Member|=Returns|=What it does
6 +|##getLayoutIds()##|An array of layout ids|Lists the layouts the reader may switch to
7 +|##getPropertyDescriptors()##|An array of property descriptors|Lists the properties the instance knows, with their type, their displayer and their filter
8 +|##updateEntries()##|Nothing|Reloads the entries, with the filters and the sort currently applied
9 +
10 +{{code language="javascript"}}
11 +jQuery("#myld").data("liveData").getLayoutIds();
12 +jQuery("#myld").data("liveData").getPropertyDescriptors();
13 +jQuery("#myld").data("liveData").updateEntries();
14 +{{/code}}
15 +
16 +== HTML Attributes ==
17 +
18 +These attributes select Live Data elements without depending on a layout, which is what makes a stylesheet or a test survive the reader switching layout.
19 +
20 +|=Attribute|=Set on|=Holds
21 +|##data-livedata-property-id##|Every property displayer|The id of the property being displayed
22 +|##data-livedata-entry-index##|The root element of an entry|The index of that entry in the page of results currently displayed
23 +|##data-livedata-entry-id##|The root element of an entry|The value identifying that entry
24 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== How do I reach the API of a Live Data whose id I know? ==
2 +
3 +Through the ##liveData## jQuery data-property of its container, as in ##jQuery("#myld").data("liveData")##.
4 +
5 +== How do I refresh a Live Data after changing its data elsewhere? ==
6 +
7 +By calling ##updateEntries##, which reloads the entries with the filters and the sort currently applied.
8 +
9 +== Why select elements through these attributes rather than through CSS classes? ==
10 +
11 +Because they are the same in every layout, so a selector built on them survives the reader switching layout.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Live Data Extension Points>>doc:documentation.xs.dev.livedata.extension-points.WebHome]]
2 +* [[Live Data Webjar API>>doc:documentation.xs.dev.livedata.webjar.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +developer
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-webjar

Creation of Debug the SQL Query of a Live Data

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Debug the SQL Query of a Live Data
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,21 @@
1 +Read the SQL query a Live Data built on the ##liveTable## [[source>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]] actually ran, when it returns the wrong entries.
2 +
3 +A live table results page answers the ##sql## request parameter by adding the query it ran, and its parameters, to its JSON response, but a Live Data never displays that extra field. The query therefore has to be logged from the results page and read from the server logs, which needs edit right on ##XWiki.LiveTableResultsMacros## and access to the "Logging" administration section.
4 +
5 +1. Open the browser developer tools on the page holding the Live Data, select the "Network" tab and filter on ##/entries## to find the URL it fetches its entries from.
6 +1. Open that URL in a new tab, with ##&sourceParams.sql=1## appended to its query string.
7 +1. Edit ##XWiki.LiveTableResultsMacros##, find ##request.sql## and add these two lines next to it:(((
8 +{{code language="velocity"}}
9 +#set ($discard = $services.logging.getLogger('XWiki.LiveTableResultsMacros').debug("SQL: $sql"))
10 +#set ($discard = $services.logging.getLogger('XWiki.LiveTableResultsMacros').debug("SQL parameters: $sqlParams"))
11 +{{/code}}
12 +)))
13 +1. Open the "Logging" administration section, search for the ##XWiki.LiveTableResultsMacros## logger and set its level to ##debug##.
14 +1. Reload the entries URL. The server logs then hold the query and its parameters:(((
15 +{{code language="none"}}
16 +DEBUG X.LiveTableResultsMacros - SQL: where 1=1 order by lower(doc.fullName) asc, doc.fullName asc
17 +DEBUG X.LiveTableResultsMacros - SQL parameters: {}
18 +{{/code}}
19 +)))
20 +1. Remove the two lines from ##XWiki.LiveTableResultsMacros## and reset the logger level.
21 +
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Why can I not just add ##sql~=1## as I would with a live table? ==
2 +
3 +Because the parameter reaches the results page, but the Live Data does not display the extra field it adds to the JSON response.
4 +
5 +== Nothing is written to the logs. What did I miss? ==
6 +
7 +Most likely the logger level, which has to be set to ##debug## on the ##XWiki.LiveTableResultsMacros## logger.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Live Data Sources>>doc:documentation.xs.user.livedata.display-data.sources.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +developer
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-livedata-macro

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Page Administration
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Hidden
... ... @@ -1,1 +1,1 @@
1 -false
1 +true
Content
XWiki.PinnedChildPagesClass[0]
Pinned child pages
... ... @@ -1,0 +1,1 @@
1 +configuration/ extension-points/ script-service/ javascript-api/ webjar/ sql-query-debugging/

Creation of Page Administration

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Page Administration
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Hidden
... ... @@ -1,1 +1,1 @@
1 -false
1 +true
Content
XWiki.PinnedChildPagesClass[0]
Pinned child pages
... ... @@ -1,0 +1,1 @@
1 +display-data/ layouts/ panels/ edit-value-place/ edit-mode/ migrate-live-table/

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.
This Change Request is ready for review.
No conflicts to show.
The change request cannot be published without valid approval or if at least one review request for changes.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected