@o2xp/react-datatable

@o2xp/react-datatable is a modulable component to render data in a table with some nice features !

See a show case just here.

Table of Contents

• Getting Started
  • Installing
  • Prop Types
    • Datatable Properties
    • Options Properties
    • Columns Props
    • Additional Icons Props
    • Additional Selection Icons Props
• Overriding
• Contributing
• Build With
• Contributors

Getting Started

Installing

$ npm i --save @o2xp/react-datatable

In your file :

// ES6
import {Datatable} from "@o2xp/react-datatable";
import React, { Component } from "react";

// Basic Example
let options  = {
    keyColumn: 'id',
    data: {
        columns: [ 
            {
                id: "id",
                label: "id",
                colSize: "80px"
            },
            {
                id: "name",
                label: "name",
                colSize: "150px"
            },
            {
                id: "age",
                label: "age",
                colSize: "50px"
            },
        ],
        rows: [
            {
                id: "50cf",
                age: 28,
                name: "Kerr Mayo"
            },
            {
                id: "209",
                age: 34,
                name: "Freda Bowman"
            },
            {
                id: "2dd81ef",
                age: 14,
                name: "Becky Lawrence"
            }
        ],
    }
}

class App extends Component {
    render() {
        return <Datatable options={options} />;
    }
}

export default App;

Attention : the column id "o2xpActions" is reserved. Using it can result of unexpected behaviours.

Live implementation

To go further check all examples

Prop Types

Datatable Properties

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | options | object | yes | An object that all the options to render the datatable. See Options Properties. | | actions | function | no | Function that take as parameter {type, payload}, where type is the action performed (save, delete etc..) and payload the data needed to perform the action. See advanced example. | | refreshRows | function | no | Function that return an an array of objects where each object is defined by the columns identifier as key and the value. See advanced example. | | forceRerender | boolean | no | Do you want to rerender the component on route change or keep the state ? | | stripped | boolean | no | Do you want stripped rows ? | | CustomTableBodyRow | function | no | Function that take { row, columnsOrder, rowIndex, columnSizeMultiplier, height } and return a react html element. See body row example. | | CustomTableBodyCell | function | no | Function that take { cellVal, column, rowId } and return a react html element. See body cell example. | | CustomTableHeaderRow | function | no | Function that take { columnsOrder, columnSizeMultiplier } and return a react html element. See header row example. | | CustomTableHeaderCell | function | no | Function that take { column } and return a react html element. See header cell example. | | customDataTypes | array | no | object that return an array of object with datatypes and react html element. See datatypes cell example. | | text | object | no | An object with text to override. See text override. | | theme | object | no | See theming. |

Options Properties

| Property | Type | Required? | Default | Description | |:---|:---:|:---:|:---:|:---| | title | string | no | " " | Title of the datatable. | | text | object | no | | Un object with key taking a string as value. Click here to have more information.| | dimensions .datatable .width | string | no | "100vw" | Width of the the Datatable. (in vw / px / %) | | dimensions .datatable .height | string | no | "300px" | Height of the Datatable. (in vh / px / %) | | dimensions .row .height | string | no | "33px" | Height of each row of the Datatable. (in px) Minimum 33px. | | keyColumn | string | yes | / | Name of the column that has unique value and allows to identify a row. | | currentScreen | string | no | / | Name of the screen that will used to differentiate created presets. If you put the same string for 2 datatables, it will show the same created presets. | | font | string | no | "Roboto" | Name of the font you are using. It allows the datatable to calculate the overlapping of cells. | | data .columns | array of object | yes | / | An array of objects where each object is defined by this keys. Click here to have more information. | | data .rows | array of object | yes | / | An array of objects where each object is defined by the columns identifier as key and the value. Click here to have more information. | | features .canEdit | boolean | no | false | If the user can edit the rows. | | features .canEditRow | (row) => boolean | no | () => true | Giving row as parameter and expecting a boolean as result. Do determine if a row is editable or not. | | features .canGlobalEdit | boolean | no | false | If the user can turn in edit mode all the rows. | | features .canPrint | boolean | no | false | If you want stripped rows. | | features .canDownload | boolean | no | false | If the user can download the data. | | features .canCreatePreset | boolean | no | false | If the user can create preset(list of columns to display). The created preset will be stored in the local storage.| | features .canSearch | boolean | no | false | If the user can filter the data by text through a search input globally. | | features .canFilter | boolean | no | false | If the user can filter the data by text through a search input based on different columns. | | features .canRefreshRows | boolean | no | false | If the user can click to refresh the rows. | | features .canOrderColumns | boolean | false | no | If the user can select the columns to display. | | features .canSelectRow | boolean | false | no | If the user can select rows. | | features .canDuplicate | boolean | false | no | If the user can duplicate row. | | features .isUpdatingRows | boolean | false | no | If you are updating rows on your side. | | features .canSaveUserConfiguration | boolean | no | false | If the user can save his columns configuration. (order and which one is displayed) | | features .userConfiguration .columnsOrder | array of strings | no | [ ] | An array of strings where the strings are the column identifier. Datatable will be rendered only with the columns present in the array. | | features .userConfiguration .copyToClipboard | boolean | no | false | If true, when the user click on cell it will copy the value in the clipboard. | | features .rowsPerPage .available | array of number and string | no | [10, 25, 50, 100, "All"] | An array with the numbers of rows per page you want available. | | features .rowsPerPage .selected | number or string | no | "All" | The number of rows per page selected by default. | | features .additionalIcons | array of object | no | [ ] | If you want to add icon which trigger a function. Click here to have more information. | | features .columnsPresetsToDisplay | array of object | no | [ ] | If you want to add predefined presets in the Display by presets Tab. Click here to have more information. | | features .additionalIcons | array of object | no | [ ] | If you want to add icon which trigger a function. Click here to have more information. | | features .selection .selectionIcons | array of object | no | [ ] | If you want to add icon which execute a function with the rows selected. Click here to have more information. |

Columns Props

Columns is an array of object construct with these keys :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | id | string | yes | Id of the column (need to be unique). | | label | string | yes | Label of the column. | | colSize | number | yes | Size of the column (needs to be in px). | | editable | boolean | no | If the each value of row corresponding to the column is editable or not. | | dataType | string | no | Possible values: "number", "text", "boolean", "date", "time", "dateTime". For more type, see override section. | | inputType | string | no | Possible values: "input", "boolean", "select", "datePicker", "timePicker", "dateTimePicker" | | dateFormatIn | string | yes (only if datatype === "date" || "time" || "dateTime") | Format of the date. | | dateFormatOut | string | yes (only if datatype === "date" || "time" || "dateTime") | Format you want to display of the date. | | values | array | yes (only if inputType === "select") | Possible values displayed in the select. | | valueVerification | function | no | If you want to verify value on save. You need to provide a function which take a parameter (the new value) and return and object in this format {error: boolean, message: string} | | mask | array of regex | no | Works only with inputType === input. To build regex see react-text-mask|

Rows Props

Rows is an array of object where each object is defined by the columns identifier as key and the value. You can add this key for edit purpose :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | editableId | Array | no | Id of the columns where fields should be editable. |

Columns Presets To Display Props

Columns Presets to display is an array of object construct with these keys :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | presetName | string | yes | Description of the preset.This string will be shown on screen. | | columnsToShow | array of string | yes | List of existing columns to show | | isActive | boolean | yes | If the box should be tick |
| type | string | yes | Must be "predefinedPreset" |

Additional Actions Props

Additional actions is an array of object construct with these keys :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | title | string | yes | Description of the button. The text will be displayed on hovering the icon | | icon | Component | yes | Use @material-ui/icons to provide an icon to display. | | onClick | function | yes | A function that take a row as parameter. The function will be triggered on click. |

Additional Icons Props

Additional icons is an array of object construct with these keys :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | title | string | yes | Description of the button. The text will be displayed on hovering the icon | | icon | Component | yes | Use @material-ui/icons to provide an icon to display. | | onClick | function | yes | A function that doesn't take parameter. The function will be triggered on click. |

Additional Selection Icons Props

Additional selection icons is an array of object construct with these keys :

| Property | Type | Required? | Description | |:---|:---:|:---:|:---| | title | string | yes | Description of the button. The text will be displayed on hovering the icon | | icon | Component | yes | Use @material-ui/icons to provide an icon to display. | | onClick | function | yes | A function that takes a parameter (the selected rows). . The function will be triggered on click.|

Text override

| Property | Type | Required? | Default value | |:---|:---:|:---:|:---| | search | string | no | "Toggle" | | searchPlaceholder | string | no | "Search.." | | edit | string | no | "Edit" | | clear | string | no | "Clear" | | save | string | no | "Save" | | delete | string | no | "Delete" | | confirmDelete | string | no | "Confirm delete" | | cancelDelete | string | no | "Cancel delete" | | download | string | no | "Download data" | | downloadTitle | string | no | "Download Data" | | downloadDescription | string | no | "Data will be exported in" | | downloadSelectedRows | string | no | "Selected rows" | | downloadCurrentRows | string | no | "Rows of current page" | | downloadAllRows | string | no | "All rows" | | display | string | no | "Display columns" | | refresh | string | no | "Refresh" | | configuration | string | no | "Configuration" | | configurationTitle | string | no | "User Configuration" | | configurationCopy | string | no | "Save cell's content to clipboard on click" | | configurationColumn | string | no | "Do you want to save the configuration of the columns and copy to clipboard feature ?" | | configurationReset | string | no | "Reset" | | configurationSave | string | no | "Save" | | create | string | no | "Create" | | createTitle | string | no | "Create a new row" | | createCancel | string | no | "Cancel" | | createSubmit | string | no | "Create" | | duplicate | string | no | "Duplicate" | | print | string | no | "Print" | | orderBy | string | no | "Order by" | | drag | string | no | "Drag" | | paginationRows | string | no | "Rows" | | paginationPage | string | no | "Page" | | createPresetTitle | string | no | "Create New Preset" | | createPresetDescription | string | no | "Select the columns to save in the preset" | | createPresetTooltipText | string | no | "Create a new preset" | | createPresetNamingPlaceholder | string | no | "Preset name" | | createPresetCancelBtn | string | no | "Cancel" | | createPresetCreateBtn | string | no | "Create" |

Overriding

Because we want flexibility for our users we decide to leave a lot of possibility to users. So what can you override ?

• datatypes - documentation
• body row - documentation
• body cell - documentation
• header row - documentation
• header cell - documentation

Contributing

Do you want to contribute to this project ? Great ! You can start by reading our contributing guide.

Build With

• React - A JavaScript library for building user interfaces
• Redux - Redux is a predictable state container for JavaScript apps
• Material-ui - React components that implement Google's Material Design
• Webpack - A bundler for javascript and friends. Packs many modules into a few bundled assets.
• Babel - Babel is a tool that helps you write code in the latest version of JavaScript. When your supported environments don't support certain features natively, Babel will help you compile those features down to a supported version.
• Storybook - Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient.
• Eslint - ESLint is an open source project originally created by Nicholas C. Zakas in June 2013. Its goal is to provide a pluggable linting utility for JavaScript.
• Jest - Jest is a delightful JavaScript Testing Framework with a focus on simplicity.
• Enzyme - Enzyme is a JavaScript Testing utility for React that makes it easier to test your React Components' output. You can also manipulate, traverse, and in some ways simulate runtime given the output.
• Prettier - Prettier is an opinionated code formatter.
• Husky - Husky can prevent bad git commit, git push and more 🐶 woof!

Contributors

• Morgan Dubois
• Mike Trieu
• Noé Carl