tbc-common-grid v0.4.4
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.values0, and is less than or equal to fieldName.values1, 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
- optional prop:
columnReorderable {Boolean}: are columns reorderable default: false
- optional prop:
isRowDraggable(row)
function
- optional prop:
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
- required prop:
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
- required prop:
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).
- optional prop:
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
andonSortingChange
become required functions - WARNING: If enableCheckboxes is true for reorderable rows, there may be some visual inconsistencies during dragging
- NOTE: a columnConfig item for key "drag" must be included
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