Back to Kibana

@kbn/unified-data-table

src/platform/packages/shared/kbn-unified-data-table/README.md

9.4.011.9 KB
Original Source

@kbn/unified-data-table

This package contains components and services for the unified data table UI (as used in Discover).

UnifiedDataTable Component

Props description:

PropertyTypeDescription
ariaLabelledBystringDetermines which element labels the grid for ARIA.
className(optional) stringOptional class name to apply.
columnsstring[]Determines ids of the columns which are displayed.
expandedDoc(optional) DataTableRecordIf set, the given document is displayed in a flyout.
enableInTableSearch(optional) booleanSet to true to allow users to search inside the table.
dataViewDataViewThe used data view.
loadingStateDataLoadingStateDetermines if data is currently loaded.
onFilterDocViewFilterFnFunction to add a filter in the grid cell or document flyout.
onResize(optional)(colSettings: { columnId: string; width: numberundefind }) => void;
onSetColumns(columns: string[], hideTimeColumn: boolean) => void;Function to set all columns.
onSort(optional)(sort: string[][]) => void;Function to change sorting of the documents, skipped when isSortEnabled is set to false.
rows(optional)DataTableRecord[]Array of documents provided by Elasticsearch.
sampleSizenumberThe max size of the documents returned by Elasticsearch.
setExpandedDoc(optional)(doc?: DataTableRecord) => void;Function to set the expanded document, which is displayed in a flyout.
settings(optional)UnifiedDataTableSettingsGrid display settings persisted in Elasticsearch (e.g. column width).
searchDescription(optional)stringSearch description.
searchTitle(optional)stringSearch title.
showTimeColbooleanDetermines whether the time columns should be displayed (legacy settings).
showFullScreenButton(optional)booleanDetermines whether the full screen button should be displayed.
isSortEnabled(optional)booleanManage user sorting control.
sortSortOrder[]Current sort setting.
isPaginationEnabled(optional)booleanManage pagination control.
controlColumnIds(optional)string[]List of used control columns (available: 'openDetails', 'select').
rowHeightState(optional)numberRow height from state.
onUpdateRowHeight(optional)(rowHeight: number) => void;Update row height state.
isPlainRecord(optional)booleanIs text base lang mode enabled.
rowsPerPageState(optional)numberCurrent state value for rowsPerPage.
onUpdateRowsPerPage(optional)(rowsPerPage: number) => void;Update rows per page state.
onFieldEdited(optional)() => void;Callback to execute on edit runtime field.
cellActionsTriggerId(optional)stringOptional triggerId to retrieve the column cell actions that will override the default ones.
servicesSee Required services list belowService dependencies.
renderDocumentView(optional)(hit: DataTableRecord,displayedRows: DataTableRecord[],displayedColumns: string[]) => JSX.Elementundefined;
configRowHeight(optional)numberOptional value for providing configuration setting for UnifiedDataTable rows height.
showMultiFields(optional)booleanOptional value for providing configuration setting for enabling to display the complex fields in the table. Default is true.
maxDocFieldsDisplayed(optional)numberOptional value for providing configuration setting for maximum number of document fields to display in the table. Default is 50.
rowAdditionalLeadingControls(optional)RowControlColumn[]Optional value for providing an list of the additional leading control columns. UnifiedDataTable includes two control columns: Open Details and Select.
totalHits(optional)numberNumber total hits from ES.
onFetchMoreRecords(optional)() => voidTo fetch more.
externalAdditionalControls(optional)React.ReactNodeOptional value for providing the additional controls available in the UnifiedDataTable toolbar to manage it's records or state. UnifiedDataTable includes Columns, Sorting and Bulk Actions.
rowsPerPageOptions(optional)number[]Optional list of number type values to set custom UnifiedDataTable paging options to display the records per page.
renderCustomGridBody(optional)(args: EuiDataGridCustomBodyProps) => React.ReactNode;An optional function called to completely customize and control the rendering of EuiDataGrid's body and cell placement.
visibleCellActions(optional)numberAn optional value for a custom number of the visible cell actions in the table. By default is up to 3.
externalCustomRenderers(optional)Record<string,(props: EuiDataGridCellValueElementProps) => React.ReactNode>;An optional settings for a specified fields rendering like links. Applied only for the listed fields rendering.
consumer(optional)stringName of the UnifiedDataTable consumer component or application.
componentsTourSteps(optional)Record<string,string>Optional key/value pairs to set guided onboarding steps ids for a data table components included to guided tour.
onUpdateDataGridDensity(optional)(DataGridDensity) => void;Optional callback when the data grid density configuration is modified.

*Required services list:

    theme: ThemeServiceStart;
    fieldFormats: FieldFormatsStart;
    uiSettings: IUiSettingsClient;
    dataViewFieldEditor: DataViewFieldEditorStart;
    toastNotifications: ToastsStart;
    storage: Storage;
    data: DataPublicPluginStart;

Usage example:

    // Add memoized component with all needed props
    <DataTable
      ariaLabelledBy="timelineDocumentsAriaLabel"
      className={'unifiedDataTableTimeline'}
      columns={['event.category', 'event.action', 'host.name', 'user.name']}
      expandedDoc={expandedDoc as DataTableRecord}
      enableInTableSearch
      dataView={dataView}
      loadingState={isQueryLoading ? DataLoadingState.loading : DataLoadingState.loaded}
      onFilter={() => {
        // Add logic to refetch the data when the filter by field was added/removed. Refetch data.
      }}
      onResize={(colSettings: { columnId: string; width: number | undefined }) => {
        // Update the table state with the new width for the column
      }}
      onSetColumns={(columns: string[], hideTimeColumn: boolean) => {
        // Update table state with the new columns. Refetch data.
      }}
      onSort={!isTextBasedQuery ? onSort : undefined
        // Update table state with the new sorting settings. Refetch data.
      }
      rows={searchResultRows}
      sampleSize={500}
      setExpandedDoc={() => {
        // Callback function to do the logic when the document is expanded
      }}
      settings={tableSettings}
      showTimeCol={true}
      isSortEnabled={true}
      sort={sortingColumns}
      rowHeightState={3}
      onUpdateRowHeight={(rowHeight: number) => {
        // Do the state update with the new setting of the row height
      }}
      isPlainRecord={isTextBasedQuery}
      rowsPerPageState={50}
      onUpdateRowsPerPage={(rowHeight: number) => {
        // Do the state update with the new number of the rows per page
      }
      onFieldEdited={() => 
        // Callback to execute on edit runtime field. Refetch data.
      }
      cellActionsTriggerId={SecurityCellActionsTrigger.DEFAULT}
      services={{
        theme,
        fieldFormats,
        storage,
        toastNotifications: toastsService,
        uiSettings,
        dataViewFieldEditor,
        data: dataPluginContract,
      }}
      visibleCellActions={3}
      externalCustomRenderers={{
        // Set the record style definition for the specific fields rendering Record<string,(props: EuiDataGridCellValueElementProps) => React.ReactNode>
      }}
      renderDocumentView={() => 
        // Implement similar callback to render the Document flyout
          const renderDetailsPanel = useCallback(
                () => (
                <DetailsPanel
                    browserFields={browserFields}
                    handleOnPanelClosed={handleOnPanelClosed}
                    runtimeMappings={runtimeMappings}
                    tabType={TimelineTabs.query}
                    scopeId={timelineId}
                    isFlyoutView
                />
                ),
                [browserFields, handleOnPanelClosed, runtimeMappings, timelineId]
            );
      }
      externalAdditionalControls={additionalControls}
      renderCustomGridBody={renderCustomGridBody}
      rowsPerPageOptions={[10, 30, 40, 100]}
      showFullScreenButton={false}
      maxDocFieldsDisplayed={50}
      consumer="timeline"
      totalHits={
        // total number of the documents in the search query result. For example: 1200
      }
      onFetchMoreRecords={() => {
        // Do some data fetch to get more data
      }}
      configRowHeight={3}
      showMultiFields={true}
      componentsTourSteps={'expandButton': DISCOVER_TOUR_STEP_ANCHOR_IDS.expandDocument}
    />

JsonCodeEditorCommon Component

Props description:

PropertyTypeDescription
width(optional) string or numberEditor component width.
height(optional) string or numberEditor component height.
hasLineNumbers(optional) booleanDefine if the editor component has line numbers style.
hideCopyButton(optional) booleanShow/hide setting for Copy button.
onEditorDidMount(editor: monaco.editor.IStandaloneCodeEditor) => voidDo some logic to update the state with the edotor component value.

Usage example:

<JsonCodeEditorCommon
    jsonValue={jsonValue}
    width={100}
    height={400}
    hasLineNumbers={true}
    onEditorDidMount={(editorNode: monaco.editor.IStandaloneCodeEditor) => setEditor(editorNode)}
/>

Utils

  • getRowsPerPageOptions(currentRowsPerPage) - gets list of the table defaults for perPage options.

  • getDisplayedColumns(currentRowsPerPage) - gets list of the table columns with the logic to define the empty list with _source column.

  • popularizeField(...) - helper function to define the dataView persistance and save indexPattern update capabilities.

Hooks

  • useColumns(...) - this hook define the state update for the columns event handlers and allows to use them for external components outside the UnifiedDataTable.

An example of using hooks for defining event handlers for columns management with setting the consumer specific setAppState:

const {
    columns: currentColumns,
    onAddColumn,
    onRemoveColumn,
    onMoveColumn,
    onSetColumns,
  } = useColumns({
    capabilities,
    defaultOrder: uiSettings.get(SORT_DEFAULT_ORDER_SETTING),
    dataView,
    dataViews,
    setAppState: stateContainer.appState.update,
    columns,
    sort,
  });

// Use onAddColumn, onRemoveColumn handlers in the DocumentView

const renderDocumentView = useCallback(
    (hit: DataTableRecord, displayedRows: DataTableRecord[], displayedColumns: string[]) => (
      <DiscoverGridFlyout
        dataView={dataView}
        hit={hit}
        hits={displayedRows}
        // if default columns are used, dont make them part of the URL - the context state handling will take care to restore them
        columns={displayedColumns}
        savedSearchId={savedSearch.id}
        onFilter={onAddFilter}
        onRemoveColumn={onRemoveColumn}
        onAddColumn={onAddColumn}
        onClose={() => setExpandedDoc(undefined)}
        setExpandedDoc={setExpandedDoc}
        query={query}
      />
    ),
    [dataView, onAddColumn, onAddFilter, onRemoveColumn, query, savedSearch.id, setExpandedDoc]
  );