@opuscapita/react-grid

    9.3.4 • Public • Published

    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.

    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.

    Keywords

    none

    Install

    npm i @opuscapita/react-grid

    DownloadsWeekly Downloads

    258

    Version

    9.3.4

    License

    MIT

    Unpacked Size

    25.9 MB

    Total Files

    74

    Last publish

    Collaborators

    • elaczapiewska
    • jarkko.rouvinen
    • bo-kh
    • pdetmer
    • janek.bug
    • alexeysergeev
    • ilkkalehtinen
    • havantkim
    • eriihine
    • tamkov-sc
    • kwierchris
    • elefantino
    • samikarj
    • dsanko
    • dmitrydivin
    • alexanderdanilov
    • egor.stambakio
    • jenni
    • ocmachineuser
    • lukaszkepa
    • naniantero
    • nkovalenko-sc
    • jluukka
    • zjuice
    • adam-dziomdziora-cybercom
    • kaputse
    • dmitriy.sanko
    • nczeranka
    • ocautomation
    • maciej-wakula-opuscapita