react-grid

Description

Datagrid is a component that can be used to present data in table. It supports inline edit, action bar and lot more. Component is highly customizable to meet different use cases.

Underneath it uses originally Facebook's, but later continued by Schrodinger fixed-data-table-2 react component, which is designed to handle large amounts amounts of data without sacraficing performance.

Installation

npm install @opuscapita/react-grid
npm install react-immutable-proptypes

Demo

View the DEMO

Change log

View the Change log

Migrate guide

View the Migrate guide between major versions

Redux dependency

Datagrid uses redux as data store, so you must have redux set up in your project. It also depends on redux-thunk and react-intl-redux to be present. These dependencies comes from the fact that this component is separated from another project and it is known that these dependencies should be removed at some point.

Usage

First you have to connect your component to the redux. Then you can map the datagrid's state and actions to your component's props. The mappings are needed only for those parts that you need in your component. For example if you only load data to the grid, you can only map the setData action. If you need to know currently selected items, you need to map selectedItems from the grid state.

• Create a GRID object that contains id and idKeyPath of your grid. This object is passed to every action you call and to the Datagrid component itself as prop.
• Create a column array that configures your grid's columns. Some actions needs this information as well.
• Add Datagrid component to your render method and pass in the grid and columns props.
• Then to set the data to the grid, call setData action with grid, columns and data parameters.
• You should now have a grid with data loaded.
• Check the API section below to see what props the Datagrid supports, also GRID object and columns are documented there.
• To see what actions are available, check the actions file.

Responsiveness

The grid component has logic to always take the space that is available on it's container component. Make sure to determine your container's width and height! If you make your container to grow and shrink with window size, the grid will follow and take the space that is has.

Grid listens to window.resize event. If you modify container size dynamically, remember to fire window.resize event to make grid follow new size. There's also redux action forceRefresh for the convenience.

Builds

UMD

The default build with compiled styles in the .js file. Also minified version available in the lib/umd directory.

CommonJS/ES Module

You need to configure your module loader to use cjs or es fields of the package.json to use these module types. Also you need to configure sass loader, since all the styles are in sass format.

• With webpack use resolve.mainFields to configure the module type.
• Add SASS loader to support importing of SASS styles.

API

Datagrid

Prop name	Type	Default	Description
grid	object	required	Grid attributes and config object
columns	array	required	Array of column configuration objects
rowsCount	number		Override rows count otherwise calculated from data
idKeyPath	array of strings		Key path to unique ID value in the grid data, used in many features like row selecting and inline editing
gridHeader	node		Grid header displayed on top of grid
actionBar	node		Action bar element displayed at top right
actionBarLeft	node		Action bar element displayed at top left
cellSelect	boolean	false	Enable cell selecting
disableDropdown	boolean	false	Don't use dropdown menu in the action bar
disableFilteringControls	boolean	false	Don't display the filtering controls (only used if disableDropdown is true)
dropdownMenuItems	array		Additional dropdown menu items
inlineEdit	boolean	false	Enable inline editing
inlineAdd	boolean	true	Enable inline adding (defaults to true if inlineEdit is enabled)
filtering	boolean	false	Enable column filtering
removing	boolean	false	Enable item removing
columnSettings	boolean	false	Enable column settings popup (column selecting and re-ordering)
rowSelect	boolean	false	Enable row selecting
rowSelectCheckboxColumn	boolean	false	Enable additional checkbox column for row selecting
multiSelect	boolean	false	Enable multi selecting on row selecting
selectComponentOptions	Immutable.Map		Options data for the react-select components
selectComponentTranslations	object		Translation strings for react-select placeholder and noResultsText texts.
isCreatableSelect	bool		With this option it's possible to create new select options on the fly
disableActions	boolean	false	Disable action bar actions, eg. when other grid busy
disableActionsMessage	object	{ messageId: 'GridActionsDisabledOtherGridBusy' }	Message about the reason of disabled action bar actions
disableActionBar	boolean	false	Disable action bar rendering
disableActionSave	boolean	false	Disable Save action button
enableArrowNavigation	boolean	false	Enable navigation with arrow keys in editing mode
onSave	function		Callback that is called when save button is clicked
onRemove	function		Callback that is called when delete is clicked
onCancel	function		Callback that is called when cancel is clicked
onAddClick	function		Callback that is called when add is clicked
onEditClick	function		Callback that is called when edit is clicked
tabIndex	number	1	tabIndex start value, needed when multiple grids on same page
extraColumn	object		Extra column that cannot be hidden or re-ordered. It's rendered always as first colunn
headerHeight	number	40	Pixel height of the header row
rowHeight	number	40	Pixel height of rows
containerStyle	object		Additional styles to be set on the container div
scrollToColumn	number		Index of column to scroll to
scrollTop	number		Value of vertical scroll
scrollToRow	number		Index of row to scroll to
scrollInEditMode	boolean	false	Allow the usage of scrollToRow in edit mode
onRowClick	function		Callback that is called when a row is clicked
onRowDoubleClick	function		Callback that is called when a row is double clicked
onRowMouseDown	function		Callback that is called when a mouse-down event happens on a row
onRowMouseEnter	function		Callback that is called when a mouse-enter event happens on a row
onRowMouseLeave	function		Callback that is called when a mouse-leave event happens on a row
onScrollStart	function		Callback that is called when scrolling starts with current horizontal and vertical scroll values
onScrollEnd	function		Callback that is called when scrolling ends or stops with new horizontal and vertical scroll values
rowClassNameGetter	function		To get any additional CSS classes that should be added to a row, rowClassNameGetter(index) is called
rowHeightGetter	function		If specified, rowHeightGetter(rowData, rowIndex) is called for each row and the returned value overrides rowHeight for particular row
onContentHeightChange	function		Callback that is called when rowHeightGetter returns a different height for a row than the rowHeight prop. This is necessary because initially table estimates heights of some parts of the content
showSelectAllCheckbox	bool	true	Show Select all checkbox in the header when rowSelectCheckboxColumn is set to true
contextMenuItems	array		Array of items in the context menu
pagination	object		Object of pagination options

Datagrid - grid prop attributes

Prop name	Type	Default	Description
id	string	required	ID of the datagrid
idKeyPath	array of strings		Key path to unique ID value in the grid data, used in many
defaultShowFilteringRow	boolean	false	Show filtering row as default
defaultSortColumn	string		columnKey of column sorted by default. ColumnKey is joined with '/' from valueKeyPath array, if columnKey is not defined in the column props
defaultSortOrder	string	'asc'	Default sort order of default sort [asc/desc]
disableRememberSelectedItems	boolean	false	Disable remembering the selected rows
disableRememberIsFiltering	boolean	false	Disable remembering is filtering ebabled
disableRememberFilterData	boolean	false	Disable remembering the filters
disableRememberSortData	boolean	false	Disable remembering the sorting
disableRememberColumnWidths	boolean	false	Disable remembering the column widths
language	string	'en'	Default taken from redux user state used in OC apps
region	string	'en-GB'	Default taken from redux user state used in OC apps
dateFormat	string	'L'	Default taken from redux user state used in OC apps
thousandSeparator	string	' '	Default taken from redux user state used in OC apps
decimalSeparator	string	'.'	Default taken from redux user state used in OC apps
pagination	boolean	false	True, if grid data is paginated. Otherwise false.

Datagrid - column prop attributes

Name	Type	Default	Description
header	node		Column header content
columnKey	string		Column identifier key (required if no valueKeyPath, otherwise autogenerated)
valueKeyPath	string		Column content value key path
valueType	string		Value type [text/number/float/boolean/date]
valueOptions	object		Options for the value rendering
componentType	string		Input component type [boolean/checkbox/currency/date/float/multiselect/number/select/text]
valueRender	function		Override value render, (rowData, rowIndex) as parameters
editValueRender	function		Override value render in editing mode, (rowData, rowIndex, setRef, onKeyDown) as parameters
editValueParser	function		Override value parser in editing mode, (value) as parameter
createValueRender	function		Override value render in creating mode, (rowData, rowIndex, setRef, onKeyDown) as parameters
filterValueRender	function		Override value render in filtering mode, (rowData, rowIndex) as parameters
cell	function		Override cell content renderer, rowIndex as parameter
cellEdit	function		Override content renderer in editing mode
cellCreate	function		Override cell content renderer in creating mode
cellFilter	function		Override cell content renderer in filtering mode
renderComponentProps	object		Additional props for the render component
editComponentProps	object		Additional props for the edit component
createComponentProps	object		Additional props for the create component
filterComponentProps	object		Additional props for the filter component
width	number	200	The pixel width of the column
minWidth	number	20	The minimum pixel width of the column
maxWidth	number		The maximum pixel width of the column
align	number		The horizontal alignment of the column
fixed	boolean		Column is fixed
fixedRight	boolean		Column is fixed to right
allowCellsRecycling	boolean		Recycle cells that are outside viewport horizontally, better horizontal scrolling performance.
disableResizing	boolean		Disable column resizing this column
disableSorting	boolean		Disable column sorting this column
disableEditing	boolean		Disable inline editing this column
flexGrow	number		The grow factor relative to other columns
valueEmptyChecker	function		Checker function defined when data is empty
sortValueGetter	function		Getter function for the sort data
sortComparator	function		Comparator function for the sort data
filterMatcher	function		Matcher function that matches filter to data (parameters: rowData, filterValue)
defaultValue	string, number		Default value for the item when creating new item
isRequired	bool		Indicating if column value is required
isHidden	bool		Column is hidden by default and can be enabled from column settings, enable columnSettings grid prop
onValueMatchChangeValue	object		Change other column value if own value matches
disableEditingOnValueMatch	object		Disable input element of this column when value at keyPath matches
onEditValueChange	function		Called on edit value change, called with (value, valueKeyPath, rowIndex, dataId)
onCreateValueChange	function		Called on create value change, called with (value, valueKeyPath, rowIndex)
onCreateBlur	function		Called on create cell input blur, called with (value, rowIndex)
onEditBlur	function		Called on edit cell input blur, called with (value, rowIndex, dataId)
onLastCellTabPress	function		Called on tab keypress in edit/create cell when the last cell in the grid is being focused, called with original KeyPress event
selectComponentOptions	array		Options data for the react-select component
translations	object		Translations object
isMultiselectTooltipDisabled	boolean	false	Tooltip that shows selected items in view mode
virtualized	boolean	false	If true and input component type is multiselect, filter option list is virtualized

Datagrid - valueOptions prop attributes for currency value type

Name	Type	Default	Description
currencyKeyPath	array	['currency']	Currency code key path to calculate number of decimals from
decimals	number		Number of decimals
thousandSeparator	string		Defaults to datagrid config
decimalSeparator	array		Defaults to datagrid config
currency	string		Defaults to datagrid config
multiplier	number		If defined, values of columns, with componentType currency, are multiplied by multiplier in view mode. Note that in create and edit mode values are real, not multiplied.

Datagrid - onValueMatchChangeValue prop attributes

Name	Type	Default	Description
matchValue	any		When this columns data match to this
newValueKeyPath	array of strings		Change value at this keyPath
newValue	any		The new value to be inserted

Datagrid - disableEditingOnValueMatch prop attributes

Name	Type	Default	Description
matchValueKeyPath	array of strings		Keypath of the value to be matched
matchValue	any		The value to be matched

Datagrid - extraColumn prop attributes

Name	Type	Default	Description
width	number	40	Column width in pixels
valueRender	function		Value render function
cellEdit	function		Render function for edit mode
cellCreate	function		Render function for create mode
cellFilter	function		Render function for create mode
isResizable	boolean	false	Is column resisable

Datagrid - contextMenuItems prop array attributes

Name	Type	Default	Description
id	string		Item id
title	any		Value to display in the menu
icon	any		Icon element to display with item
onClick	function		onClick handles, parameters (selectedIds :: List, selectedData :: List)
disabled	boolean, function	false	Is item disabled, parameters (selectedIds :: List, selectedData :: List)

Datagrid - contextMenuItems prop array attributes

Name	Type	Default	Description
value	any		Value to display in the menu
onClick	function		onClick handles, parameters (selectedIds :: List, selectedData :: List)
title	string		Item title to show when mouse overing
disabled	boolean, function	false	Is item disabled, parameters (selectedIds :: List, selectedData :: List)
header	boolean	false	Is item a header
divider	boolean	false	Is item a divider

Datagrid - pagination prop attributes

Name	Type	Default	Description
pageSize	number		Row count on page
totalLimit	number		Limit for total amount of rows
totalSize	number		Total amount of rows
getData	function		Callback function to request paginated data, parameters (offset :: number, count :: number, filters :: Map, sortColumn :: string or number, sortOrder :: string)

Datagrid column - translations prop attributes

Name	Type	Default	Description
columnHeaderTooltip	string or node		Specifies optional tooltip for column header

Code example

import React from 'react';
import { Datagrid } from '@opuscapita/react-grid';

export default class DatagridView extends React.Component {
  render() {
    const GRID = {
      id: 'accounts', // unique id for the grid
      idKeyPath: ['accountId'], // path to unique Id in the data to separate rows from eachother
    };
    const columns = [
      {
        header: 'Account Name',
        valueKeyPath: ['name'],
        valueType: 'text',
        width: 200,
      },
      {
        header: 'Account number',
        valueKeyPath: ['accountNumber'],
        valueType: 'text',
        width: 200,
      },
      {
        header: 'Amount',
        valueKeyPath: ['amount'],
        valueType: 'currency',
        valueOtions: {
          decimals: 3,
        },
        width: 200,
      },
    ];

    return (
      <Datagrid
        grid={GRID}
        columns={columns}
      />
    );
  }
}

Troubleshooting

• Grid shows only headers, not the data.
  • Determine the height of your container with CSS. Grid will expand to it's container size!
  • If you know that your other components height in the page is 100px, you can set grid container height to calc(100% - 100px) for responsiveness.