|
| 1 | +# TOAST UI Grid for React |
| 2 | + |
| 3 | +> This is a React component wrapping [TOAST UI Grid](https://github.com/nhnent/tui.grid). |
| 4 | +
|
| 5 | +[](https://github.com/nhnent/toast-ui.react-grid/releases/latest) |
| 6 | +[](https://www.npmjs.com/package/@toast-ui/react-grid) |
| 7 | +[](https://github.com/nhnent/toast-ui.react-grid/blob/master/LICENSE) |
| 8 | +[](https://github.com/nhnent/toast-ui.react-grid/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) |
| 9 | +[](https://github.com/nhnent) |
| 10 | + |
| 11 | +## 🚩 Table of Contents |
| 12 | +* [Collect statistics on the use of open source](#collect-statistics-on-the-use-of-open-source) |
| 13 | +* [Install](#-install) |
| 14 | + * [Using npm](#using-npm) |
| 15 | +* [Usage](#-usage) |
| 16 | + * [Load](#load) |
| 17 | + * [Implement](#implement) |
| 18 | + * [Props](#props) |
| 19 | + * [Event](#event) |
| 20 | + * [Method](#method) |
| 21 | +* [Pull Request Steps](#-pull-request-steps) |
| 22 | +* [Documents](#-documents) |
| 23 | +* [Contributing](#-contributing) |
| 24 | +* [License](#-license) |
| 25 | + |
| 26 | +## Collect statistics on the use of open source |
| 27 | + |
| 28 | +React Wrapper of TOAST UI Grid applies Google Analytics (GA) to collect statistics on the use of open source, in order to identify how widely TOAST UI Grid is used throughout the world. It also serves as important index to determine the future course of projects. location.hostname (e.g. > “ui.toast.com") is to be collected and the sole purpose is nothing but to measure statistics on the usage. To disable GA, use the following `usageStatistics` option when declare React Wrapper compoent. |
| 29 | + |
| 30 | +```js |
| 31 | +var options = { |
| 32 | + ... |
| 33 | + usageStatistics: false |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +Or, import `tui-code-snippet.js` (**v1.4.0** or **later**) and then immediately write the options as follows: |
| 38 | +```js |
| 39 | +tui.usageStatistics = false; |
| 40 | +``` |
| 41 | + |
| 42 | +## 💾 Install |
| 43 | + |
| 44 | +### Using npm |
| 45 | + |
| 46 | +```sh |
| 47 | +npm install --save @toast-ui/react-grid |
| 48 | +``` |
| 49 | + |
| 50 | +## 🔡 Usage |
| 51 | + |
| 52 | +### Import |
| 53 | + |
| 54 | +You can use Toast UI Grid for React as a ECMAScript module or a CommonJS module. As this module does not contain CSS files, you should import `tui-grid.css` from `tui-grid` manually. |
| 55 | + |
| 56 | +* Using ECMAScript module |
| 57 | + |
| 58 | +```js |
| 59 | +import 'tui-grid/dist/tui-grid.css' |
| 60 | +import Grid from '@toast-ui/react-grid' |
| 61 | +``` |
| 62 | + |
| 63 | +* Using CommonJS module |
| 64 | + |
| 65 | +```js |
| 66 | +require('tui-grid/dist/tui-grid.css'); |
| 67 | +const Grid = require('@toast-ui/react-grid'); |
| 68 | +``` |
| 69 | + |
| 70 | +### Props |
| 71 | + |
| 72 | +[All the options of the TOAST UI Grid](http://nhnent.github.io/tui.grid/latest/Grid) are supported in the form of props. |
| 73 | + |
| 74 | +```js |
| 75 | +const data = [ |
| 76 | + {id: 1, name: 'Editor'}, |
| 77 | + {id: 2, name: 'Grid'} |
| 78 | + {id: 3, name: 'Chart'} |
| 79 | +]; |
| 80 | + |
| 81 | +const columns = [ |
| 82 | + {name: 'id', title: 'ID'}, |
| 83 | + {name: 'name', title: 'Name'} |
| 84 | +]; |
| 85 | + |
| 86 | +const MyComponent = () => ( |
| 87 | + <Grid |
| 88 | + data={data} |
| 89 | + columns={columns} |
| 90 | + bodyHeight={100} |
| 91 | + /> |
| 92 | +); |
| 93 | +``` |
| 94 | + |
| 95 | +### Reactive Props |
| 96 | + |
| 97 | +Normally, React Components are re-rendered whenever the props received from a parent Component are changed. But not all the props of this Component are reactive as the TOAST UI Grid does not provide setter methods for all options. Below are the list of reactive props which are currently supported. |
| 98 | + |
| 99 | +- data (using `setData`) |
| 100 | +- columns (using `setColumns`) |
| 101 | +- bodyHeight (using `setBodyHeight`) |
| 102 | +- frozenColumnCount (using `setFrozenColumnCount`) |
| 103 | + |
| 104 | +If you don't want some props to be reactive, you can disable reactivity of specific props using `oneTimeBindingProps`. For example, if you don't want to re-render whenever `data` and `columns` props are changed, you can use `oneTimeBindingProps` like example below. |
| 105 | + |
| 106 | +```js |
| 107 | + |
| 108 | +const MyComponent = () => ( |
| 109 | + <Grid |
| 110 | + data={data} |
| 111 | + columns={columns} |
| 112 | + bodyHeight={100} |
| 113 | + oneTimeBindingProps={['data', 'columns']} |
| 114 | + /> |
| 115 | +); |
| 116 | +``` |
| 117 | + |
| 118 | +### Methods (Using Ref) |
| 119 | + |
| 120 | +For using methods of TOAST UI Grid instance, first thing to do is creating Refs of wrapper Component using `createRef()`. The wrapper Component does not provide a way to call methods of TOAST UI Grid instance directly. Instead, you can call `getGridInstance()` method of the wrapper Component to get the instance, and call the methods with it. |
| 121 | + |
| 122 | +```js |
| 123 | +class MyComponent extends React.Component { |
| 124 | + gridRef = React.createRef(); |
| 125 | + |
| 126 | + handleAppendRow = () => { |
| 127 | + this.gridRef.current.getGridInstance().appendRow({}); |
| 128 | + } |
| 129 | + |
| 130 | + render() { |
| 131 | + return ( |
| 132 | + <> |
| 133 | + <Grid |
| 134 | + ref={this.gridRef} |
| 135 | + data={data} |
| 136 | + columns={columns} |
| 137 | + bodyHeight={100} |
| 138 | + /> |
| 139 | + <button onClick={this.handleAppendRow}>Append Row</button> |
| 140 | + </> |
| 141 | + |
| 142 | + ); |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +### Static Methods |
| 148 | + |
| 149 | + |
| 150 | + |
| 151 | + |
| 152 | +### Event |
| 153 | + |
| 154 | + |
| 155 | +## 🔧 Pull Request Steps |
| 156 | + |
| 157 | +TOAST UI products are open source, so you can create a pull request(PR) after you fix issues. |
| 158 | +Run npm scripts and develop yourself with the following process. |
| 159 | + |
| 160 | +### Setup |
| 161 | + |
| 162 | +Fork `develop` branch into your personal repository. |
| 163 | +Clone it to local computer. Install node modules. |
| 164 | +Before starting development, you should check to haveany errors. |
| 165 | + |
| 166 | +``` sh |
| 167 | +$ git clone https://github.com/{your-personal-repo}/[[repo name]].git |
| 168 | +$ cd [[repo name]] |
| 169 | +$ npm install |
| 170 | +``` |
| 171 | + |
| 172 | +### Develop |
| 173 | + |
| 174 | +Let's start development! |
| 175 | + |
| 176 | +### Pull Request |
| 177 | + |
| 178 | +Before PR, check to test lastly and then check any errors. |
| 179 | +If it has no error, commit and then push it! |
| 180 | + |
| 181 | +For more information on PR's step, please see links of Contributing section. |
| 182 | + |
| 183 | +## 📙 Documents |
| 184 | +* [Getting Started](https://github.com/nhnent/toast-ui.react-grid/blob/master/docs/getting-started.md) |
| 185 | + |
| 186 | +## 💬 Contributing |
| 187 | +* [Code of Conduct](https://github.com/nhnent/toast-ui.react-grid/blob/master/CODE_OF_CONDUCT.md) |
| 188 | +* [Contributing guideline](https://github.com/nhnent/toast-ui.react-grid/blob/master/CONTRIBUTING.md) |
| 189 | +* [Commit convention](https://github.com/nhnent/toast-ui.react-grid/blob/master/docs/COMMIT_MESSAGE_CONVENTION.md) |
| 190 | + |
| 191 | +## 📜 License |
| 192 | +This software is licensed under the [MIT](./LICENSE) © [NHN Ent.](https://github.com/nhnent) |
0 commit comments