tbc-common-grid

CommonGrid Module

import CommonGridContainer from "tbc-common-grid/dist/Component/CommonGridContainer";

<CommonGridContainer {...props} />

Props

columnsConfig:

Object with each column (by dataField), each with own object with following props:

| Prop | Type | Required | Default | Description | | ------------------- | -------- | -------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | title | String | Required | dataField | column header title | | relativeWidth | Number | Optional | 1 | relative column width; used to determine column width relative to others columns | | minWidth | Number | Optional | 0 | minimum pixel width that column cannot be smaller than | | align | String | Optional | "left" | alignment of contents of column ("left", "center", or "right") | | compare | Function | Optional | | comparison function used for column sorting | | getCellValue | Function | Optional | () => return dataFieldValue | function used to translate dataField into a different visual value; this could a dictionary translation of code to name, a mathematical calculation, etc. | | showWhenGrouped | Boolean | Optional | false | if set to true, column will show even if grouped by that column | | sortingEnabled | Boolean | Optional | true | | if set to false, sorting for column is disabled. |

Example 1:

columnsConfig: {
    firstColumn: {
        title: "First Column",
        relativeWidth: 1,
        minWidth: 100,
        align: "right"
    }
};

Example 2:

columnsConfig => props => {
    const { dictionary } = props;
    return {
        firstColumn: {
            title: "First Column",
            relativeWidth: 1,
            minWidth: 100,
            align: "right",
            compare: customCompareFunction
        },
        secondColumn: {
            title: "Second Column",
            relativeWidth: 1.5,
            minWidth: 150,
            getCellValue: row => {
                return dictionary.columnCodes[row.secondColumn].name;
            }
        }
    }
};

gridData

Array of data objects to be displayed in grid.

NOTE: For best results with sorting, derived fields (fields created from either multiple other fields or have heavy dictionary-based manipulations) should be included as part of these data objects.

filters

OPTIONAL: Object of field_names, each containing an object:

• type {String: "includes", "excludes", "range", "dateRange"}: determines what type of filtering takes place [default: "includes"]:

  • "includes" - if item.field includes any item in the fieldName.values, it is displayed
  • "excludes" - if item.field includes any item in the fieldName.values, it is NOT displayed
  • "range" - if item.field is greater than or equal to fieldName.values[0], and is less than or equal to fieldName.values[1], it is displayed.
  • "daterange" - as with "range", only specific to dates

• values {Array}: values to be filtered against; if empty, then no filter is applied for that field.

Example:

The following will return only items with a "firstColumn" value of "One". Because the "secondColumn" filter is empty, items with any secondColumn value (as long as they have firstColumn value of "One") will be displayed. If "secondColumn.values" array wasn't empty, because it's type is "excludes", any item contain secondColumn value of any of those items would be filtered out.

const filters = {
  firstColumn: { values: ["One"] },
  secondColumn: { type: "excludes", values: [] }
};

gridConfig:

Object containing configuration options for the grid. All are optional.

• defaultSorting {Array}: array of columnName/direction objects that determine default sorting; if empty, then no sorting is applied [default: null]

  • optional prop: sortingArray array
  • optional prop: onSortingChange(sortingArray) function

• columnReorderable {Boolean}: are columns reorderable [default: false]

  • optional prop: isRowDraggable(row) function

• enableCheckboxes {Boolean}: provide table and row checkboxes

  • required prop: checkBoxFuncs object
  • NOTE: a columnConfig item for key "checkboxSpacer" must be included checkboxSpacer: { title: " ", relativeWidth: 0.4, minWidth: 45 }
  • WARNING: If rowReoderable is true for checkbox selectable rows, there may be some visual inconsistencies during dragging

• enableDetailRow {Boolean}: do rows have detail rows

  • required prop: RowDetail component
  • NOTE: a columnConfig item for key "detailSpacer" must be included detailSpacer: { title: " ", relativeWidth: 0.4, minWidth: 45 }

• enableRowSelection {Boolean}: are rows selectable [default: false]

  • required prop: selectRow(row) function

• grouping {Array}: array of columnName objects that determine default grouping; if empty, then no grouping is applied [default: null]

  • optional prop: groupList array
  • WARNING: It is not recommended to have Grouping enabled if Pagination is enabled (it is best to have only one or the other).

• height {Number}: if non-zero, sets height for virtual table

• pagination {object}: if exists, pagination is available:

Prop	Type	Default	Description
defaultCurrentPage	Number	0	zero-index page number
defaultPageSize	Number	10	number of items shown
pageSizes	Array	[]	array of available page sizes

• required prop: paginationObj object

• WARNING: It is not recommended to have Pagination enabled if Grouping is enabled (it is best to have only one or the other).

• rowReorderable {Boolean}: are rows reorderable [default: false]

  • NOTE: a columnConfig item for key "drag" must be included drag: { title: " ", relativeWidth: 0.4, minWidth: 45 }
  • NOTE: for rowReorderable, sortingArray and onSortingChange become required functions
  • WARNING: If enableCheckboxes is true for reorderable rows, there may be some visual inconsistencies during dragging

• staticColumnWidth {Boolean}: if set to true, columns will NOT be resizable [default: false]

• hideHeader {Boolean}: if set to true, the table header row will not be displayed [default: false]

• defaultExpandedRowIndices {Array}: Array of indices of the detail rows that should be expanded by default [default: [] ]

  • NOTE: enableRowDetail must be set to true for this to apply

gridWidth

Numerical value for the width of the grid (in pixels), used with relativeWidth to dynamically determin column widths

shownColumns

Array of columns names that are displayed, and in what order

getRowClass

Optional function that receives row value and returns a string of CSS classes that can be applied to the row.

Example: The following will apply the class "color-warning" to any row with a status value of "warning", else it will apply class "color-safe":

<CommonGridContainer
  getRowClass={row => {
    if (row.status === "warning") {
      return "color-warning"
    }
    return "color-safe"
  }}
/>

NOTE: This module contains the built-in classes: bg-blue, bg-red, bg-green, bg-yellow, and bg-grey (for appropriately colored background); any other styles will need to be assessible by the parent component.

Optional Utility Props in Support of Enabled Features

checkBoxFuncs

Object of functions used if table has enableCheckboxes set to true:

• getRowStatus(row) {Function}: param of row; returns status of row checkbox ("checked", "unchecked", "disabled")
• getTableStatus() {Function}: returns status of header checkbox ("checked", "unchecked", "partial", "disabled")
• checkSelectRow(row) {Function}: param of row; fired when row checkbox is clicked
• checkSelectAllRows() {Function}: fired when table header checkbox is clicked

columnOrderObj

Object used if columnReorderable is enabled:

• columnOrder {Array}: array of columns by order (defaults to shownColumn array)
• setColumnOrder(ArrayOfColumnNames) {Function}: function called when columns are reordered

groupList

Array of values that, when grouping is enabled, determine which groups are expanded by default.

isRowDraggable(row)

Function used in rowReordering to return if row should be draggable or not [default: () => return true]

onSortingChange(sortingArray)

Function fired when sorting is performed

paginationObj

If using external pagination (either store-based or api-based), pass this object into the component:

• currentPage {Number}: the zero-index current page
• pageSize {Number}: the current page size
• setCurrentPage(pageNumber) {Function}: the function to set your current page; sends page index
• setPageSize(pageSize) {Function}: the function to set your page size; sends page size
• totalCount {Number}: the total number of rows

rightClickReordering

Function called when right-click reorder menu selection made; returns row and "first" or "last"

rightClickReordering: (row, moveTo) => {
  console.log("rightClickReordering:", row, moveTo);
}

RowDetail

JSX Element used as detail row; receives rowProps.row props

const ThisRowDetail = rowProps => {
  const { row } = rowProps;
  return (
    <div>{JSON.stringify(row)}</div>
  );
};

selectRow

Function fired when row is selected; returns row

selectRow: row => {
  console.log("selectRow:", row);
}

setGridData

Function used to set/change data (rows) at parent level when changed in common grid.

sortingArray

Array of sorting objects (columnName/direction); used if sorting is stored external to common grid.

expandedRowArray

Array of row ids corresponding to which row has been expanded (when using RowDetail).

onExpandedRowChange

Function used to set/change data (row ids) for expanded rows (when using RowDetail).

Additional Functions

• The CommonGrid uses a getFilteredData(data, filter) function to apply filters to the data. This function can be called upstream by importing it from {CommonGrid}/Utils/getFilteredData.

import { getFilteredData } from "{path}/CommonGrid/Utils/commonGridUtils";

• getFilteredData take two parameters: the data and the filters array from gridConfig, and returns the filtered data as an array.

Required Modules

• @devexpress/dx-react-grid and @devexpress/dx-react-grid-material-ui (npm install --save @material-ui/icons @devexpress/dx-react-core @devexpress/dx-react-grid @devexpress/dx-react-grid-material-ui @material-ui/icons) https://devexpress.github.io/devextreme-reactive/react/grid/
• React Sortable HOC (npm install --save react-sortable-hoc) https://github.com/clauderic/react-sortable-hoc
• React Context Menu (npm install --save react-contextmenu) https://www.npmjs.com/package/react-contextmenu
• Array Move (npm install array-move) https://www.npmjs.com/package/array-move

Sample Component

import SampleComponentContainer from "tbc-common-grid/dist/Sample/SampleComponentContainer";

Testing

For any unit test file that deep renders ("mounts") this imported component, add the following:

jest.mock("tbc-common-grid/dist/Component/CommonGridContainer", () => "div");

Change Log

• 0.4.0 : Updated checkboxes to use MaterialUI's built-in Checkbox component
• 0.4.1 : Fixed table row checkboxes so that they use onClick instead of onChange