Wiki source code of Live Data API
Last modified by Manuel Leduc on 2026/03/24 09:38
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{version since="18.2.0RC1"}} | ||
| 2 | == ActionDescriptor == | ||
| 3 | |||
| 4 | Describes a live data action. | ||
| 5 | |||
| 6 | {{code language="typescript"}} | ||
| 7 | interface ActionDescriptor { | ||
| 8 | allowProperty?: string; | ||
| 9 | id: string; | ||
| 10 | } | ||
| 11 | {{/code}} | ||
| 12 | |||
| 13 | === Properties === | ||
| 14 | |||
| 15 | * ##id##: The action id. | ||
| 16 | * ##allowProperty##: An optional boolean property id. This property is going to be used to determine if the action is allowed for a given entry. | ||
| 17 | |||
| 18 | == Data == | ||
| 19 | |||
| 20 | Stores the entries to display (paginated) and the total count of entries. | ||
| 21 | |||
| 22 | {{code language="typescript"}} | ||
| 23 | interface Data { | ||
| 24 | count: number; | ||
| 25 | entries: Values[]; | ||
| 26 | } | ||
| 27 | {{/code}} | ||
| 28 | |||
| 29 | === Properties === | ||
| 30 | |||
| 31 | * ##count##: The total number of entries. | ||
| 32 | * ##entries##: The list of entries to display (paginated). | ||
| 33 | |||
| 34 | == DisplayerDescriptor == | ||
| 35 | |||
| 36 | |||
| 37 | Holds the displayer configuration. | ||
| 38 | |||
| 39 | {{code language="typescript"}} | ||
| 40 | interface DisplayerDescriptor { | ||
| 41 | id: string; | ||
| 42 | } | ||
| 43 | {{/code}} | ||
| 44 | |||
| 45 | === Properties === | ||
| 46 | |||
| 47 | * ##id##: The displayer id. | ||
| 48 | |||
| 49 | == EntryDescriptor == | ||
| 50 | |||
| 51 | Describes a live data entry. | ||
| 52 | |||
| 53 | {{code language="typescript"}} | ||
| 54 | interface EntryDescriptor { | ||
| 55 | idProperty: string; | ||
| 56 | } | ||
| 57 | {{/code}} | ||
| 58 | |||
| 59 | === Properties === | ||
| 60 | |||
| 61 | * ##idProperty##: The id of the described property. | ||
| 62 | |||
| 63 | == Filter == | ||
| 64 | |||
| 65 | A set of constraints to apply to a given property. | ||
| 66 | |||
| 67 | {{code language="typescript"}} | ||
| 68 | interface Filter { | ||
| 69 | constraints: QueryConstraint[]; | ||
| 70 | matchAll: boolean; | ||
| 71 | property: string; | ||
| 72 | } | ||
| 73 | {{/code}} | ||
| 74 | |||
| 75 | === Properties === | ||
| 76 | |||
| 77 | |||
| 78 | * ##constraints##: The set of constraints to apply on the query. | ||
| 79 | * ##matchAll##: When true, all the constraints must be true for the filter to allow the entry to be displayed. When false, only on of the constraint must be true. | ||
| 80 | * ##property##: The property of filter. | ||
| 81 | |||
| 82 | |||
| 83 | == FilterDescriptor == | ||
| 84 | |||
| 85 | |||
| 86 | Holds the filter configuration. | ||
| 87 | |||
| 88 | {{code language="typescript"}} | ||
| 89 | interface FilterDescriptor { | ||
| 90 | defaultOperator: string; | ||
| 91 | id: string; | ||
| 92 | operators: OperatorDescriptor[]; | ||
| 93 | } | ||
| 94 | {{/code}} | ||
| 95 | |||
| 96 | === Properties === | ||
| 97 | |||
| 98 | |||
| 99 | * ##defaultOperator##: The default filter operator for this filter. | ||
| 100 | * ##id##: The filter id. | ||
| 101 | * ##operators##: The list of operators supported by this filter. | ||
| 102 | |||
| 103 | == LayoutDescriptor == | ||
| 104 | |||
| 105 | Holds the layout configuration. | ||
| 106 | |||
| 107 | {{code language="typescript"}} | ||
| 108 | interface LayoutDescriptor { | ||
| 109 | id: string; | ||
| 110 | } | ||
| 111 | {{/code}} | ||
| 112 | |||
| 113 | === Properties === | ||
| 114 | |||
| 115 | * ##id##: The id of the layout. | ||
| 116 | |||
| 117 | == LiveDataSource == | ||
| 118 | |||
| 119 | The component that provides the live data entries and their metadata. | ||
| 120 | |||
| 121 | {{code language="typescript"}} | ||
| 122 | interface LiveDataSource { | ||
| 123 | getEntries(query: Query): Promise<Data>; | ||
| 124 | updateEntry( | ||
| 125 | source: Source, | ||
| 126 | entryId: string, | ||
| 127 | values: unknown, | ||
| 128 | ): Promise<void>; | ||
| 129 | updateEntryProperty( | ||
| 130 | source: Source, | ||
| 131 | entryId: string, | ||
| 132 | propertyId: string, | ||
| 133 | value: unknown, | ||
| 134 | ): Promise<void>; | ||
| 135 | } | ||
| 136 | {{/code}} | ||
| 137 | |||
| 138 | === Methods === | ||
| 139 | |||
| 140 | * ##getEntries##: Fetch the entries from a given live data source based on the provided query. The result is a paginated results plus the total number of entries. | ||
| 141 | * ##updateEntry##: the query of apply when fetching the entries | ||
| 142 | * ##updateEntryProperty##: a promise with the fetched data | ||
| 143 | |||
| 144 | == Logic == | ||
| 145 | |||
| 146 | Present the public API of the logic used inside the Live Data UI. It provides the operations and data to display Live Datas. It is build to be shared by most of the UI elements of a Live Data. | ||
| 147 | |||
| 148 | {{code language="typescript"}} | ||
| 149 | interface Logic { | ||
| 150 | currentLayoutId?: Ref<string, string>; | ||
| 151 | data?: { | ||
| 152 | data: { count: number; entries: Values[] }; | ||
| 153 | id: number; | ||
| 154 | meta: { | ||
| 155 | actions: { allowProperty?: string; id: string }[]; | ||
| 156 | defaultDisplayer: string; | ||
| 157 | defaultLayout: string; | ||
| 158 | displayers: { id: string }[]; | ||
| 159 | entryDescriptor: { idProperty: string }; | ||
| 160 | filters: { | ||
| 161 | defaultOperator: string; | ||
| 162 | id: string; | ||
| 163 | operators: { id: string; name: string }[]; | ||
| 164 | }[]; | ||
| 165 | layouts: { id: string }[]; | ||
| 166 | propertyDescriptors: { | ||
| 167 | displayer: { id: string }; | ||
| 168 | editable?: boolean; | ||
| 169 | filter: { | ||
| 170 | constraints: { operator: string; value: unknown }[]; | ||
| 171 | matchAll: boolean; | ||
| 172 | property: string; | ||
| 173 | }; | ||
| 174 | filterable?: boolean; | ||
| 175 | id: string; | ||
| 176 | sortable?: boolean; | ||
| 177 | type: string; | ||
| 178 | visible?: boolean; | ||
| 179 | }[]; | ||
| 180 | propertyTypes: { | ||
| 181 | displayer: { id: string }; | ||
| 182 | editable?: boolean; | ||
| 183 | filter: { | ||
| 184 | constraints: { operator: string; value: unknown }[]; | ||
| 185 | matchAll: boolean; | ||
| 186 | property: string; | ||
| 187 | }; | ||
| 188 | filterable?: boolean; | ||
| 189 | id: string; | ||
| 190 | sortable?: boolean; | ||
| 191 | type: string; | ||
| 192 | visible?: boolean; | ||
| 193 | }[]; | ||
| 194 | selection: { enabled: boolean }; | ||
| 195 | }; | ||
| 196 | query: { | ||
| 197 | filters: { | ||
| 198 | constraints: { operator: string; value: unknown }[]; | ||
| 199 | matchAll: boolean; | ||
| 200 | property: string; | ||
| 201 | }[]; | ||
| 202 | limit: number; | ||
| 203 | offset: number; | ||
| 204 | properties: string[]; | ||
| 205 | sort: { descending: boolean; property: string }[]; | ||
| 206 | source: { id: string; [key: string]: string }; | ||
| 207 | }; | ||
| 208 | }; | ||
| 209 | addFilter( | ||
| 210 | property: string, | ||
| 211 | operator: unknown, | ||
| 212 | value: string, | ||
| 213 | index: number, | ||
| 214 | ): Promise<void>; | ||
| 215 | addSort(property: string, descending: boolean | undefined): Promise<void>; | ||
| 216 | changeLayout(layoutId: string): void; | ||
| 217 | filter( | ||
| 218 | property: string, | ||
| 219 | index: number, | ||
| 220 | filterEntry: { index: number }, | ||
| 221 | operator: { filterOperator?: unknown; skipFetch?: boolean }, | ||
| 222 | ): Promise<void>; | ||
| 223 | getEntryId(entry: Values): string | undefined; | ||
| 224 | getPageCount(): number; | ||
| 225 | isContentTrusted(): boolean; | ||
| 226 | onEvent(event: string, callback: (e: Event) => void): void; | ||
| 227 | onEventWhere( | ||
| 228 | eventName: string, | ||
| 229 | condition: object | ((p: unknown) => boolean), | ||
| 230 | callback: (e: Event) => void, | ||
| 231 | ): void; | ||
| 232 | registerPanel(panel: Panel): void; | ||
| 233 | removeFilter(property: string, index: number): Promise<void>; | ||
| 234 | removeSort(property: string): Promise<void>; | ||
| 235 | reorderSort(propertyId: string, toIndex: number): void; | ||
| 236 | setElement(element: HTMLElement): void; | ||
| 237 | setValues(entryId: { entryId: string; values: unknown }): Promise<unknown>; | ||
| 238 | sort(property: string, level: number, descending?: boolean): Promise<void>; | ||
| 239 | translationsLoaded(): Promise<boolean>; | ||
| 240 | triggerEvent(eventName: string, eventData?: object): void; | ||
| 241 | updateEntries(): Promise<void>; | ||
| 242 | } | ||
| 243 | {{/code}} | ||
| 244 | |||
| 245 | === Properties === | ||
| 246 | |||
| 247 | * ##currentLayoutId#: The id of the current layout.## | ||
| 248 | * ##data#: The Live Data data, fetch from a source.## | ||
| 249 | |||
| 250 | === Methods === | ||
| 251 | |||
| 252 | * ##addFilter##: Add new filter entry, shorthand of filter: | ||
| 253 | * ##addSort##: Add new sort entry, shorthand of sort: If the property is already sorting, does nothing | ||
| 254 | * ##changeLayout##: Load a layout, or default layout if none specified | ||
| 255 | * ##filter##: Update filter configuration based on parameters, then fetch new data. | ||
| 256 | * ##getEntryId##: Return the id of the given entry. | ||
| 257 | * ##getPageCount##: Get total number of pages | ||
| 258 | * ##isContentTrusted##: When true, the content is trusted. When false, the content is not trusted and will be sanitized. | ||
| 259 | * ##onEvent##: Listen for an event. | ||
| 260 | * ##onEventWhere##: Listen for custom events, matching certain conditions. | ||
| 261 | * ##registerPanel##: Registers a panel. | ||
| 262 | * ##removeFilter##: Remove a filter entry in the configuration, then fetch new data | ||
| 263 | * ##removeSort##: Remove a sort entry, shorthand of sort: | ||
| 264 | * ##reorderSort##: Move a sort entry to a certain index in the query sort list | ||
| 265 | * ##setElement##: Set the root element of the Live Data. | ||
| 266 | * ##setValues##: Update the entry with the values object passed in parameter | ||
| 267 | * ##sort##: Update sort configuration based on parameters, then fetch new data | ||
| 268 | * ##translationsLoaded##: A promise completing when the translations are loaded. It can contain true if the translations loaded successfully, false otherwise. | ||
| 269 | * ##triggerEvent##: Send custom events. The livedata object reference is automatically added. | ||
| 270 | * ##updateEntries##: Trigger a refresh of the Live Data. | ||
| 271 | |||
| 272 | == LogicData == | ||
| 273 | |||
| 274 | The data stored in a Logic object. It contains the metadata of a Live Data, the query used to fetch the data, and the data themselves. | ||
| 275 | |||
| 276 | {{code language="typescript"}} | ||
| 277 | interface LogicData { | ||
| 278 | data: Data; | ||
| 279 | id: number; | ||
| 280 | meta: Meta; | ||
| 281 | query: Query; | ||
| 282 | } | ||
| 283 | {{/code}} | ||
| 284 | |||
| 285 | === Properties === | ||
| 286 | |||
| 287 | * ##data##: Holds the data | ||
| 288 | * ##id##: The id of a livedata | ||
| 289 | * ##meta##: The metadata of a Live Data, stores the descriptor for the displayers, filters, layout, or actions. | ||
| 290 | * ##query##: Holds the query parameters used to retrieve the Live Data data. | ||
| 291 | |||
| 292 | == Meta == | ||
| 293 | |||
| 294 | Describes the configuration used to display the live data. | ||
| 295 | |||
| 296 | {{code language="typescript"}} | ||
| 297 | interface Meta { | ||
| 298 | actions: ActionDescriptor[]; | ||
| 299 | defaultDisplayer: string; | ||
| 300 | defaultLayout: string; | ||
| 301 | displayers: DisplayerDescriptor[]; | ||
| 302 | entryDescriptor: EntryDescriptor; | ||
| 303 | filters: FilterDescriptor[]; | ||
| 304 | layouts: LayoutDescriptor[]; | ||
| 305 | propertyDescriptors: PropertyDescriptor[]; | ||
| 306 | propertyTypes: PropertyDescriptor[]; | ||
| 307 | selection: { enabled: boolean }; | ||
| 308 | } | ||
| 309 | {{/code}} | ||
| 310 | |||
| 311 | === Properties === | ||
| 312 | |||
| 313 | * ##actions##: The descriptors of supported live data actions | ||
| 314 | * ##defaultDisplayer##: The default displayer used to display live data properties. | ||
| 315 | * ##defaultLayout##: The default layout used to display the live data | ||
| 316 | * ##displayers##: The list of known property displayers | ||
| 317 | * ##entryDescriptor##: The descriptor of the live data entries. | ||
| 318 | * ##filters##: The list of known filter widgets. | ||
| 319 | * ##layouts##: Sets the list of supported layouts. | ||
| 320 | * ##propertyDescriptors##: The list of known properties. | ||
| 321 | * ##propertyTypes##: The list of known property types. | ||
| 322 | * ##selection##: The live data entry selection. Note: the selection implementation is currently incomplete. | ||
| 323 | |||
| 324 | == OperatorDescriptor == | ||
| 325 | |||
| 326 | An operator to use when filtering the live data. | ||
| 327 | |||
| 328 | {{code language="typescript"}} | ||
| 329 | interface OperatorDescriptor { | ||
| 330 | id: string; | ||
| 331 | name: string; | ||
| 332 | } | ||
| 333 | {{/code}} | ||
| 334 | |||
| 335 | === Properties === | ||
| 336 | |||
| 337 | * ##id##: The operator id | ||
| 338 | * ##name##: The operator pretty name. | ||
| 339 | |||
| 340 | == Panel == | ||
| 341 | |||
| 342 | Holds all the information required to describe a panel. | ||
| 343 | |||
| 344 | {{code language="typescript"}} | ||
| 345 | interface Panel { | ||
| 346 | component: string; | ||
| 347 | container?: Element; | ||
| 348 | icon: string; | ||
| 349 | id: string; | ||
| 350 | name: string; | ||
| 351 | order: number; | ||
| 352 | title: string; | ||
| 353 | } | ||
| 354 | {{/code}} | ||
| 355 | |||
| 356 | === Properties === | ||
| 357 | |||
| 358 | |||
| 359 | * ##component##: the component id of the panel, should be "LiveDataAdvancedPanelExtension" for extension panels | ||
| 360 | * ##container?##: the Element that shall be attached to the extension panel's body, this should contain the main UI | ||
| 361 | * ##icon##: the name of the icon for the menu and the title of the panel | ||
| 362 | * ##id##: the id of the panel, must be unique among all panels, also used as suffix of the class on the panel | ||
| 363 | * ##name##: the name that shall be shown in the menu | ||
| 364 | * ##order##: the ordering number, panels are sorted by this number in ascending order | ||
| 365 | * ##title##: the title that shall be displayed in the title bar of the panel | ||
| 366 | |||
| 367 | == PropertyDescriptor == | ||
| 368 | |||
| 369 | Describes how the user interacts with a given property. | ||
| 370 | |||
| 371 | {{code language="typescript"}} | ||
| 372 | interface PropertyDescriptor { | ||
| 373 | displayer: DisplayerDescriptor; | ||
| 374 | editable?: boolean; | ||
| 375 | filter: Filter; | ||
| 376 | filterable?: boolean; | ||
| 377 | id: string; | ||
| 378 | sortable?: boolean; | ||
| 379 | type: string; | ||
| 380 | visible?: boolean; | ||
| 381 | } | ||
| 382 | {{/code}} | ||
| 383 | |||
| 384 | === Properties === | ||
| 385 | |||
| 386 | * ##displayer##: The display of the property. | ||
| 387 | * ##editable?##: true when the property is editable. | ||
| 388 | * ##filter##: The filter of the property. | ||
| 389 | * ##filterable?##: true when the property is filterable. | ||
| 390 | * ##id##: The property id. | ||
| 391 | * ##sortable?##: true when the property is sortable. | ||
| 392 | * ##type##: The property type. | ||
| 393 | |||
| 394 | == Query == | ||
| 395 | |||
| 396 | The query used to get the live data. | ||
| 397 | |||
| 398 | {{code language="typescript"}} | ||
| 399 | interface Query { | ||
| 400 | filters: Filter[]; | ||
| 401 | limit: number; | ||
| 402 | offset: number; | ||
| 403 | properties: string[]; | ||
| 404 | sort: SortEntry[]; | ||
| 405 | source: Source; | ||
| 406 | } | ||
| 407 | {{/code}} | ||
| 408 | |||
| 409 | === Properties === | ||
| 410 | |||
| 411 | * ##filters##: The filters to apply on the property values. | ||
| 412 | * ##limit##: The number of entries to fetch (the page size). | ||
| 413 | * ##offset##: The index where the current page of entries starts | ||
| 414 | * ##properties##: The list of properties whose values we want to fetch. | ||
| 415 | * ##sort##: The list of properties to sort on, along with their corresponding sort direction. | ||
| 416 | * ##source##: Where to take the data from | ||
| 417 | |||
| 418 | == QueryConstraint == | ||
| 419 | |||
| 420 | A constraint to apply to a property value. | ||
| 421 | |||
| 422 | {{code language="typescript"}} | ||
| 423 | interface QueryConstraint { | ||
| 424 | operator: string; | ||
| 425 | value: unknown; | ||
| 426 | } | ||
| 427 | {{/code}} | ||
| 428 | |||
| 429 | === Properties === | ||
| 430 | |||
| 431 | * ##operator##: The operation id (e.g., "equals") | ||
| 432 | * ##value##: An arbitrary value to apply on the operator (e.g., a string to use for the equals comparion). | ||
| 433 | |||
| 434 | == SortEntry == | ||
| 435 | |||
| 436 | A sort entry. | ||
| 437 | |||
| 438 | {{code language="typescript"}} | ||
| 439 | interface SortEntry { | ||
| 440 | descending: boolean; | ||
| 441 | property: string; | ||
| 442 | } | ||
| 443 | {{/code}} | ||
| 444 | |||
| 445 | === Properties === | ||
| 446 | |||
| 447 | * ##descending##: When true sort descending, or ascending when false. | ||
| 448 | * ##property##: The id of the property to sort. | ||
| 449 | |||
| 450 | == Source == | ||
| 451 | |||
| 452 | Specifies where to take the data from. Represents the "from" clause. | ||
| 453 | |||
| 454 | {{code language="typescript"}} | ||
| 455 | Source: { id: string } & { [key: string]: string } | ||
| 456 | {{/code}} | ||
| 457 | |||
| 458 | == Values == | ||
| 459 | |||
| 460 | The values of an entry, an arbitrary maps of key and values. | ||
| 461 | |||
| 462 | {{code language="typescript"}} | ||
| 463 | Values: { [key: string]: string } | ||
| 464 | {{/code}} | ||
| 465 | {{/version}} |
