XWiki 18.2.0+

ActionDescriptor

Describes a live data action.

interface ActionDescriptor {
    allowProperty?: string;
    id: string;
}

Properties

• id: The action id.
• allowProperty: An optional boolean property id. This property is going to be used to determine if the action is allowed for a given entry.

Data

Stores the entries to display (paginated) and the total count of entries.

interface Data {
    count: number;
    entries: Values[];
}

Properties

• count: The total number of entries.
• entries: The list of entries to display (paginated).

DisplayerDescriptor

  
  Holds the displayer configuration.

interface DisplayerDescriptor {
    id: string;
}

Properties

• id: The displayer id.

EntryDescriptor

Describes a live data entry.

interface EntryDescriptor {
    idProperty: string;
}

Properties

• idProperty: The id of the described property.

Filter

A set of constraints to apply to a given property.

interface Filter {
    constraints: QueryConstraint[];
    matchAll: boolean;
    property: string;
}

Properties

• constraints: The set of constraints to apply on the query.
• 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.
• property: The property of filter.
    

FilterDescriptor

  
Holds the filter configuration.

interface FilterDescriptor {
    defaultOperator: string;
    id: string;
    operators: OperatorDescriptor[];
}

Properties

• defaultOperator: The default filter operator for this filter.
• id: The filter id.
• operators: The list of operators supported by this filter.

LayoutDescriptor

Holds the layout configuration.

interface LayoutDescriptor {
    id: string;
}

Properties

• id: The id of the layout.

LiveDataSource

The component that provides the live data entries and their metadata.

interface LiveDataSource {
    getEntries(query: Query): Promise<Data>;
    updateEntry(
        source: Source,
        entryId: string,
        values: unknown,
    ): Promise<void>;
    updateEntryProperty(
        source: Source,
        entryId: string,
        propertyId: string,
        value: unknown,
    ): Promise<void>;
}

Methods

• 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.
• updateEntry: the query of apply when fetching the entries
• updateEntryProperty: a promise with the fetched data

Logic

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.

interface Logic {
    currentLayoutId?: Ref<string, string>;
    data?: {
        data: { count: number; entries: Values[] };
        id: number;
        meta: {
            actions: { allowProperty?: string; id: string }[];
            defaultDisplayer: string;
            defaultLayout: string;
            displayers: { id: string }[];
            entryDescriptor: { idProperty: string };
            filters: {
                defaultOperator: string;
                id: string;
                operators: { id: string; name: string }[];
            }[];
            layouts: { id: string }[];
            propertyDescriptors: {
                displayer: { id: string };
                editable?: boolean;
                filter: {
                    constraints: { operator: string; value: unknown }[];
                    matchAll: boolean;
                    property: string;
                };
                filterable?: boolean;
                id: string;
                sortable?: boolean;
                type: string;
                visible?: boolean;
            }[];
            propertyTypes: {
                displayer: { id: string };
                editable?: boolean;
                filter: {
                    constraints: { operator: string; value: unknown }[];
                    matchAll: boolean;
                    property: string;
                };
                filterable?: boolean;
                id: string;
                sortable?: boolean;
                type: string;
                visible?: boolean;
            }[];
            selection: { enabled: boolean };
        };
        query: {
            filters: {
                constraints: { operator: string; value: unknown }[];
                matchAll: boolean;
                property: string;
            }[];
            limit: number;
            offset: number;
            properties: string[];
            sort: { descending: boolean; property: string }[];
            source: { id: string; [key: string]: string };
        };
    };
    addFilter(
        property: string,
        operator: unknown,
        value: string,
        index: number,
    ): Promise<void>;
    addSort(property: string, descending: boolean | undefined): Promise<void>;
    changeLayout(layoutId: string): void;
    filter(
        property: string,
        index: number,
        filterEntry: { index: number },
        operator: { filterOperator?: unknown; skipFetch?: boolean },
    ): Promise<void>;
    getEntryId(entry: Values): string | undefined;
    getPageCount(): number;
    isContentTrusted(): boolean;
    onEvent(event: string, callback: (e: Event) => void): void;
    onEventWhere(
        eventName: string,
        condition: object | ((p: unknown) => boolean),
        callback: (e: Event) => void,
    ): void;
    registerPanel(panel: Panel): void;
    removeFilter(property: string, index: number): Promise<void>;
    removeSort(property: string): Promise<void>;
    reorderSort(propertyId: string, toIndex: number): void;
    setElement(element: HTMLElement): void;
    setValues(entryId: { entryId: string; values: unknown }): Promise<unknown>;
    sort(property: string, level: number, descending?: boolean): Promise<void>;
    translationsLoaded(): Promise<boolean>;
    triggerEvent(eventName: string, eventData?: object): void;
    updateEntries(): Promise<void>;
}

Properties

• currentLayoutId#: The id of the current layout.
• data#: The Live Data data, fetch from a source.

Methods

• addFilter: Add new filter entry, shorthand of filter:
• addSort: Add new sort entry, shorthand of sort: If the property is already sorting, does nothing
• changeLayout: Load a layout, or default layout if none specified
• filter: Update filter configuration based on parameters, then fetch new data.
• getEntryId: Return the id of the given entry.
• getPageCount: Get total number of pages
• isContentTrusted: When true, the content is trusted. When false, the content is not trusted and will be sanitized.
• onEvent: Listen for an event.
• onEventWhere: Listen for custom events, matching certain conditions.
• registerPanel: Registers a panel.
• removeFilter: Remove a filter entry in the configuration, then fetch new data
• removeSort: Remove a sort entry, shorthand of sort:
• reorderSort: Move a sort entry to a certain index in the query sort list
• setElement: Set the root element of the Live Data.
• setValues: Update the entry with the values object passed in parameter
• sort: Update sort configuration based on parameters, then fetch new data
• translationsLoaded: A promise completing when the translations are loaded. It can contain true if the translations loaded successfully, false otherwise.
• triggerEvent: Send custom events. The livedata object reference is automatically added.
• updateEntries: Trigger a refresh of the Live Data.

LogicData

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.

interface LogicData {
    data: Data;
    id: number;
    meta: Meta;
    query: Query;
}

Properties

• data: Holds the data
• id: The id of a livedata
• meta: The metadata of a Live Data, stores the descriptor for the displayers, filters, layout, or actions.
• query: Holds the query parameters used to retrieve the Live Data data.

Meta

Describes the configuration used to display the live data.

interface Meta {
    actions: ActionDescriptor[];
    defaultDisplayer: string;
    defaultLayout: string;
    displayers: DisplayerDescriptor[];
    entryDescriptor: EntryDescriptor;
    filters: FilterDescriptor[];
    layouts: LayoutDescriptor[];
    propertyDescriptors: PropertyDescriptor[];
    propertyTypes: PropertyDescriptor[];
    selection: { enabled: boolean };
}

Properties

• actions: The descriptors of supported live data actions
• defaultDisplayer: The default displayer used to display live data properties.
• defaultLayout: The default layout used to display the live data
• displayers: The list of known property displayers
• entryDescriptor: The descriptor of the live data entries.
• filters: The list of known filter widgets.
• layouts: Sets the list of supported layouts.
• propertyDescriptors: The list of known properties.
• propertyTypes: The list of known property types.
• selection: The live data entry selection. Note: the selection implementation is currently incomplete.

OperatorDescriptor

An operator to use when filtering the live data.

interface OperatorDescriptor {
    id: string;
    name: string;
}

Properties

• id: The operator id
• name: The operator pretty name.

Panel

Holds all the information required to describe a panel.

interface Panel {
    component: string;
    container?: Element;
    icon: string;
    id: string;
    name: string;
    order: number;
    title: string;
}

Properties

• component: the component id of the panel, should be "LiveDataAdvancedPanelExtension" for extension panels
• container?: the Element that shall be attached to the extension panel's body, this should contain the main UI
• icon: the name of the icon for the menu and the title of the panel
• id: the id of the panel, must be unique among all panels, also used as suffix of the class on the panel
• name: the name that shall be shown in the menu
• order: the ordering number, panels are sorted by this number in ascending order
• title: the title that shall be displayed in the title bar of the panel

PropertyDescriptor

Describes how the user interacts with a given property.

interface PropertyDescriptor {
    displayer: DisplayerDescriptor;
    editable?: boolean;
    filter: Filter;
    filterable?: boolean;
    id: string;
    sortable?: boolean;
    type: string;
    visible?: boolean;
}

Properties

• displayer: The display of the property.
• editable?: true when the property is editable.
• filter: The filter of the property.
• filterable?: true when the property is filterable.
• id: The property id.
• sortable?: true when the property is sortable.
• type: The property type.

Query

The query used to get the live data.

interface Query {
    filters: Filter[];
    limit: number;
    offset: number;
    properties: string[];
    sort: SortEntry[];
    source: Source;
}

Properties

• filters: The filters to apply on the property values.
• limit: The number of entries to fetch (the page size).
• offset: The index where the current page of entries starts
• properties: The list of properties whose values we want to fetch.
• sort: The list of properties to sort on, along with their corresponding sort direction.
• source: Where to take the data from

QueryConstraint

A constraint to apply to a property value.

interface QueryConstraint {
    operator: string;
    value: unknown;
}

Properties

• operator: The operation id (e.g., "equals")
• value: An arbitrary value to apply on the operator (e.g., a string to use for the equals comparion).

SortEntry

A sort entry.

interface SortEntry {
    descending: boolean;
    property: string;
}

Properties

• descending: When true sort descending, or ascending when false.
• property: The id of the property to sort.

Source

Specifies where to take the data from. Represents the "from" clause.

Source: { id: string } & { [key: string]: string }

Values

The values of an entry, an arbitrary maps of key and values.

Values: { [key: string]: string }