Wiki source code of Live Data Configuration
Last modified by Eleni Cojocariu on 2026/09/11 15:51
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 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}} |
