## Introduction
This document is a migration guide for the TOAST UI Grid 3.0 version update, which will help you migrate to the 3.0 version quickly and easily, and introduce new features.
In the meantime, the TOAST UI's application products have been redesigned to strengthen the TOAST UI brand.
With the 3.0 version update, the grid also applies a new design.
Theme API options are enhanced to allow for more detailed style settings for new designs.
In addition, the feature to display the tree data is added.
Please refer to the contents below and upgrade to version 3.0!
## 1. Apply New Design
Now you can make your grid look cool instantly.
No hard work is required.
You only need to change the JavaScript and CSS files to the new version.
_If you are using bower or CDN, be sure to update [`tui-code-snippet`](https://github.com/nhnent/tui.code-snippet) to version **1.4.0**._
### Using `npm`
* Update the `package.json` dependency version.
``` js
{
"dependencies": {
"tui-grid": "^3.0.0"
}
}
```
### Using CDN
``` html
...
...
```
### Note
The default value of options related to row height has been changed according to the changed design.
| Option | Before | After |
| --- | ---- | ---- |
| `minRowHeight` | `35px` | `40px` |
| `header.height` | `27px` | `40px` |
It is recommended to set the default value or more for design optimization, but if you want to set a value below, you can do the following.
After setting the `minRowHeight` value of the grid options, change the cell's padding value by overriding the CSS style.
``` js
var options = {
minRowHeight: 27
};
```
``` css
.tui-grid-cell .tui-grid-cell-content {
padding: 3px 12px;
}
```
## 2. Theme API Options
If the layout of the previous version was closed type, it was changed to open layout in version 3.0.
As a result, unnecessary options using for the theme API have been removed.
Several options have been added to change styles in more detail.
```js
var Grid = require('tui-grid');
Grid.applyTheme('striped');
Grid.applyTheme('clean');
Grid.applyTheme('default', {
// theme options
});
```
### Removed Options
* `grid` : The common border and area have been removed, so this option has been deprecated.
```js
{
grid: {
background: '#fff',
border: '#ccc',
text: '#444'
}
}
```
### Added Options
#### 1. Layout-Related Options
* `outline` : Changes the outline style of the table.
```js
{
outline: {
border: 'red',
showVerticalBorder: true
}
}
```
* `frozenBorder` : Changes the border color for seperating frozen column areas.
```js
{
frozenBorder: {
border: 'red'
}
}
```
* `scrollbar.border` : Changes the border color for the scrollbar area.
* `scrollbar.emptySpace `: Changes the background color for the rest area except the scrollbar.
```js
{
scrollbar: {
border: 'red',
emptySpace: 'pink'
}
}
```
#### 2. Area-Related Options
* `area` : Changes the border and background color for header, body, and summary areas.
```js
{
area: {
header: {
border: 'blue',
background: 'skyblue'
},
body: {
background: 'yellow'
},
summary: {
border: 'red',
background: 'pink'
}
}
}
```
#### 3. Cell-Related Options
* `cell.rowHead` : Changes the cell style of the meta-column area.
* `cell.selectedRowHead` : Changes the cell style of the selected meta-column area.
* `cell.summary` : Changes the cell style of the summary area.
```js
{
cell: {
rowHead: {
background: 'pink',
border: 'red',
text: 'red',
showVerticalBorder: true,
showHorizontalBorder: true
},
selectedRowHead: {
background: '#e5f6ff'
},
summary: {
background: 'pink',
border: 'red',
text: 'red',
showVerticalBorder: true
}
}
}
```
## 3. Tree Column
### Description
* When a tree column is set, the data of a specific column is displayed in the tree form.
* Tree Elements and Functions
* Depth : Represents a hierarchical relationship between parent and child rows. The minimum depth starts with `1`.
* Expand/Collapse button : It is created on the parent row that has a child row, and child rows are visible or hidden.
* Icon : You can use a status icon that shows whether a parent row has child rows.
### How to Use
#### 1. Set Tree Data
* Initialize the row data(`{}`) in an array(`[]`) like the common grid data.
* If there are child rows, add the row data for each child row in the `_children` property of the parent row data.
* You can handle dynamic loading by setting the `_children` property to a` boolean` value.
* The `_extraData.treeState` property allows you to set the initial state of the expand or collapse for child rows. If not set, the default state is collapsed(`COLLAPSE`).
```js
var data = [
{
c1: 'foo',
c2: 'bar',
_extraData: {
treeState: 'EXPAND' // 'COLLAPSE'
},
_children: [
{
c1: 'baz',
c2: 'qux'
},
{
c1: 'quux',
c2: 'corge',
_children: true
},
// ...
]
},
// ...
];
```
#### 2. Activate Tree Column
* You can add options to the grid creation options.
| Option | Description |
| --- | --- |
| `name` | Sets column name to display tree data |
| `useIcon` | Sets whether to use the icon |
| `useCascadingCheckbox` | Sets whether to change state of the checkbox with keeping parent-child relationship |
``` js
var options = {
treeColumnOptions: {
name: 'c1',
useIcon: true,
useCascadingCheckbox: true
},
// ...
}
```
### New APIs
#### 1. Method
```js
// Example
grid.expandAll();
```
| Name | Description |
| --- | --- |
| `expand` | Expands the child rows of a particular row |
| `expandAll` | Expands all child rows |
| `collapse` | Collapses the child rows of a particular row |
| `collapseAll` | Collapses all child rows |
| `getAncestors` | Returns the row key value of all ancestor rows |
| `getDescendants` | Returns the row key value of all descendant rows |
| `getParent` | Returns the row key value of the parent row |
| `getChildren` | Returns the row key value of child rows |
| `getDepth` | Returns the depth value of the current row |
#### 2. Custom Event
```js
// Example
grid.on('expanded', function(ev) {
console.log(ev.rowKey);
});
```
| Name | Description |
| --- | --- |
| `expanded` | Occurs when the child rows of a particular row are expanded |
| `expandedAll` | Occurs when all child rows are expanded |
| `collapsed` | Occurs when the child rows of a particular row are collapsed |
| `collapsedAll` | Occurs when all child rows are collapsed |
#### 3. Parameter of `appendRow` API
```js
// Example
var options = {
parentRowKey: 3,
offset: 0,
// ...
};
grid.appendRow(row, options);
```
| Name | Description |
| --- | --- |
| `parentRowKey` | The row key value to append child rows |
| `offset` | If the parent already has child rows, determine where to add it |
### Behavior Changed APIs
The basic behavior of some API is changing when a tree column is activated.
| Name | Description |
| --- | --- |
| `appendRow` | Creates child rows below current row |
| `prependRow` | Creates child rows below current row |
| `removeRow` | If there are child rows, deletes them together |
| `check` | If sets `useCascadingCheckbox: true`, changes state of the checkbox with keeping the parent-child relationship |
| `uncheck` | If sets `useCascadingCheckbox: true`, changes state of the checkbox width keeping the parent-child relationship |
### Notice
* When using a tree column, there are restrictions on the use of **sorting**, **row merging**, **pagination**.
### Reference
More information can be found in the links below.
* [Example](https://nhnent.github.io/tui.grid/latest/tutorial-example14-tree.html)
* [APIs](https://nhnent.github.io/tui.grid/latest/Grid.html)