From 202f84702beef15c5a147a462d25aff647f3dd7d Mon Sep 17 00:00:00 2001 From: AllenFang Date: Tue, 9 Jan 2018 23:41:00 +0800 Subject: [PATCH] initial getting started adn finish the api docs --- docs/about.md | 16 ++ docs/cell-edit-props.md | 56 ++++ docs/column-props.md | 565 +++++++++++++++++++++++++++++++++++++++ docs/filter-props.md | 6 + docs/getting-started.md | 46 ++++ docs/pagination-props.md | 112 ++++++++ docs/row-select-props.md | 172 ++++++++++++ docs/table-props.md | 280 +++++++++++++++++++ docs/usage.md | 7 + 9 files changed, 1260 insertions(+) create mode 100644 docs/about.md create mode 100644 docs/cell-edit-props.md create mode 100644 docs/column-props.md create mode 100644 docs/filter-props.md create mode 100644 docs/getting-started.md create mode 100644 docs/pagination-props.md create mode 100644 docs/row-select-props.md create mode 100644 docs/table-props.md create mode 100644 docs/usage.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..9ec511f --- /dev/null +++ b/docs/about.md @@ -0,0 +1,16 @@ +--- +id: about +title: react-bootstrap-table2 +sidebar_label: About +--- + +[`react-bootstrap-table2`](https://github.com/react-bootstrap-table/react-bootstrap-table2) is next generation of [`react-bootstrap-table`](https://github.com/AllenFang/react-bootstrap-table). We rebuilt it to makie it more better and easy to use. Following is our mission: + +* Refactoring core module and make challenges be possible +* More customizable table +* Reduce the bugs and bundled size +* Solve the performance issue +* Improve the [`remote mode`](https://allenfang.github.io/react-bootstrap-table/docs.html#remote) +* Improve handling of DOM events well +* Support nest data +* Support table footer \ No newline at end of file diff --git a/docs/cell-edit-props.md b/docs/cell-edit-props.md new file mode 100644 index 0000000..5749e1d --- /dev/null +++ b/docs/cell-edit-props.md @@ -0,0 +1,56 @@ +--- +id: cell-edit-props +title: Cell Editing Props +--- + +## Required +* [mode (**required**)](#celleditmode-string) + +## Optional +* [blurToSave](#celleditblurtosave-bool) +* [nonEditableRows](#celleditnoneditablerows-function) +* [timeToCloseMessage](#celledittimetoclosemessage-function) +* [beforeSaveCell](#celleditbeforesavecell-function) +* [afterSaveCell](#celleditaftersavecell-function) +* [errorMessage](#cellediterrormessage-string) +* [onErrorMessageDisappear](#celleditonerrormessagedisappear-function) + +----- + +## cellEdit.mode - [String] +`cellEdit.mode` possible value is `click` and `dbclick`. **It's required value** that tell `react-bootstrap-table2` how to trigger the cell editing. + +## cellEdit.blurToSave - [Bool] +Default is `false`, enable it will be able to save the cell automatically when blur from the cell editor. + +## cellEdit.nonEditableRows - [Function] +`cellEdit.nonEditableRows` accept a callback function and expect return an array which used to restrict all the columns of some rows as non-editable. So the each item in return array should be rowkey(`keyField`) + +## cellEdit.timeToCloseMessage - [Function] +If a [`column.validator`](./column-props.html#columnvalidator-function) defined and the new value is invalid, `react-bootstrap-table2` will popup a alert at the bottom of editor. `cellEdit.timeToCloseMessage` is a chance to let you decide how long the alert should be stay. Default is 3000 millisecond. + +## cellEdit.beforeSaveCell - [Function] +This callback function will be called before triggering cell update. + +```js +const cellEdit = { + // omit... + beforeSaveCell: (oldValue, newValue, row, column) => { ... } +} +``` + +## cellEdit.afterSaveCell - [Function] +This callback function will be called after updating cell. + +```js +const cellEdit = { + // omit... + afterSaveCell: (oldValue, newValue, row, column) => { ... } +}; +``` + +## cellEdit.errorMessage - [String] +This prop is not often used. Only used when you want to keep the error message in your application state and also handle the cell editing on [`remote`](./table-props.html#remote-bool-object) mode. + +## cellEdit.onErrorMessageDisappear - [Function] +This callback function will be called when error message discard so that you can sync the newest error message to your state if you have. \ No newline at end of file diff --git a/docs/column-props.md b/docs/column-props.md new file mode 100644 index 0000000..42124dc --- /dev/null +++ b/docs/column-props.md @@ -0,0 +1,565 @@ +--- +id: column-props +title: Columns Props +--- + +Definition of columns props on BootstrapTable + +## Required +* [dataField (**required**)](#columndatafield-required-string) +* [text (**required**)](#columntext-required-string) + +## Optional +* [hidden](#columnhidden-bool) +* [formatter](#columnformatter-function) +* [formatExtraData](#columnformatextradata-any) +* [sort](#columnsort-bool) +* [sortFunc](#columnsortfunc-function) +* [classes](#columnclasses-string-function) +* [style](#columnstyle-object-function) +* [title](#columntitle-bool-function) +* [events](#columnevents-object) +* [align](#columnalign-string-function) +* [attrs](#columnattrs-object-function) +* [headerFormatter](#columnheaderformatter-function) +* [headerClasses](#columnheaderclasses-string-function) +* [headerStyle](#columnheaderstyle-object-function) +* [headerTitle](#columnheadertitle-bool-function) +* [headerEvents](#columnheaderevents-object) +* [headerAlign](#columnheaderalign-string-function) +* [headerAttrs](#columnheaderattrs-object-function) +* [headerSortingClasses](#headersortingclasses-string-function) +* [headerSortingStyle](#headersortingstyle-object-function) +* [editable](#columneditable-bool-function) +* [validator](#columnvalidator-function) +* [editCellStyle](#columneditcellstyle-object-function) +* [editCellClasses](#columneditcellclasses-string-function) +* [filter](#columnfilter-object) +* [filterValue](#columnfiltervalue-function) + +----- + +## column.dataField (**required**) - [String] +Use `dataField` to specify what field should be apply on this column. If your raw data is nested, for example: + +```js +const row = { + id: 'A001', + address: { + postal: '1234-12335', + city: 'Chicago' + } +} +``` +You can use `dataField` with dot(`.`) to describe nested object: + +```js +dataField: 'address.postal' +dataField: 'address.city' +``` + +## column.text (**required**) - [String] +`text` will be the column text in header column by default, if your header is not only text or you want to customize the header column, please check [`column.headerFormatter`](#columnheaderformatter-function) + +## column.hidden - [Bool] +`hidden` allow you to hide column when `true` given. + +## column.formatter - [Function] +`formatter` allow you to customize the table column and only accept a callback function which take four arguments and a JSX/String are expected for return. + +* `cell` +* `row` +* `rowIndex` +* [`formatExtraData`](#columnformatextradata-any) + +## column.headerFormatter - [Function] +`headerFormatter` allow you to customize the header column and only accept a callback function which take three arguments and a JSX/String are expected for return. + +* `column`: current column object itself +* `colIndex`: index of current column +* `components`: an object which contain all of other react element, like sort caret or filter etc. + +The third argument: `components` have following specified properties: +```js +{ + sortElement, // sort caret element, it will not be undefined when you enable sort on this column + filterElement // filter element, it will not be undefined when you enable column.filter on this column +} +``` + +## column.formatExtraData - [Any] +It's only used for [`column.formatter`](#columnformatter-function), you can define any value for it and will be passed as fourth argument for [`column.formatter`](#columnformatter-function) callback function. + +## column.sort - [Bool] +Enable the column sort via a `true` value given. + +## column.sortFunc - [Function] +`column.sortFunc` only work when `column.sort` is enable. `sortFunc` allow you to define your sorting algorithm. This callback function accept four arguments: + +```js +{ + // omit... + sort: true, + sortFunc: (a, b, order, dataField) => { + if (order === 'asc') return a - b; + else return b - a; + } +} +``` +> The possible value of `order` argument is **`asc`** and **`desc`**. + +## column.classes - [String | Function] +It's availabe to have custom class on table column: + +```js +{ + // omit... + classes: 'id-custom-cell' +} +``` +In addition, `classes` also accept a callback function which have more power to custom the css class on each columns. This callback function take **4** arguments and a `String` is expected to return: + + +```js +{ + classes: function callback(cell, row, rowIndex, colIndex) { ... } +} +``` + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result as element class. + +## column.headerClasses - [String | Function] +It's similar to [`column.classes`](#columnclasses-string-function), `headerClasses` is availabe to have customized class on table header column: + +```js +{ + // omit... + headerClasses: 'id-custom-cell' +} +``` +Furthermore, it also accept a callback function which takes 2 arguments and a `String` is expect to return: + +```js +{ + headerClasses: function callback(column, colIndex) { ... } +} +``` + +**Parameters** +* `column`: The value of current column. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result of element headerClasses. + +## column.style - [Object | Function] +It's availabe to have custom style on table column: + +```js +{ + // omit... + style: { backgroundColor: 'green' } +} +``` + +In addition, similar to [`column.classes`](#columnclasses-string-function), `style` also accept a callback function which have more power to customize the `inline style` on each columns. This callback function takes **4** arguments and an `Object` is expect to return: + + +```js +{ + style: function callback(cell, row, rowIndex, colIndex) { ... } +} +``` + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `Object` will be the result of element style. + + +## column.headerStyle - [Object | Function] +It's availabe to have customized inline-style on table header column: + +```js +{ + // omit... + headerStyle: { backgroundColor: 'green' } +} +``` + +Moreover, it also accept a callback function which takes 2 arguments and an `Object` is expect to return: + +```js +{ + headerStyle: function callback(column, colIndex) { ... } +} +``` + +**Parameters** +* `column`: The value of current column. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `Object` will be the result of element headerStyle. + + +## column.title - [Bool | Function] +`react-bootstrap-table2` is disable [`HTML title`](https://www.w3schools.com/tags/tag_title.asp) as default. You can assign `title` as `true` to enable the HTML title on table column and take `cell content` as default value. Additionally, you could customize title via a callback. It takes **4** arguments and a `String` is expect to return: + + +```js +{ + // omit... + title: function callback(cell, row, rowIndex, colIndex) { ... } + // return custom title here +} +``` + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result of element title. + +## column.headerTitle - [Bool | Function] +`headerTitle` is only for the title on header column, default is disable. The usage almost same as [`column.title`](#columntitle-bool-function), + +```js +{ + // omit... + headerTitle: true +} +``` + +It's also availabe to custom via a callback function: +```js +{ + headerTitle: function callback(column, colIndex) { ... } +} +``` + +**Parameters** +* `column`: The value of current column. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result of element headerTitle. + +## column.align - [String | Function] +You can configure the [CSS text-align](https://www.w3schools.com/cssref/pr_text_text-align.asp) for table column by `align` property. + +Besides, `align` also accept a callback function for dynamically setting text align. It takes **4** arguments and a `String` is expect to return: + +```js +{ + // omit... + align: function callback(cell, row, rowIndex, colIndex) { ... } +} +``` + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result of element text alignment. + +## column.headerAlign - [String | Function] +It's almost same as [`column.align`](#columnalign-string-function), but it's for the [CSS text-align](https://www.w3schools.com/cssref/pr_text_text-align.asp) on header column. + +```js +{ + // omit... + headerAlign: 'center' +} +``` + +Also, you can custom the align by a callback function: + +```js +{ + // omit... + headerAlign: (column, colIndex) => { + // column is an object and perform itself + // return custom title here + } +} +``` +**Parameters** +* `column`: The value of current column. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `String` will be the result of element headerAlign. + + +## column.events - [Object] +You can assign any [HTML Event](https://www.w3schools.com/tags/ref_eventattributes.asp) on table column via event property: + +```js +{ + // omit... + events: { + onClick: e => { ... } + } +} +``` + +## column.headerEvents - [Object] +`headerEvents` same as [`column.events`](#columnevents-object) but this is for header column. + +```js +{ + // omit... + headerEvents: { + onClick: e => { ... } + } +} +``` + +## column.attrs - [Object | Function] +Via `attrs` property, You can customize table column [HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) which allow user to configure the elements or adjust their behavior. + +```js +{ + // omit... + attrs: { + title: 'bar', + 'data-test': 'foo' + } +} +``` +Not only `Object`, `callback function` is also acceptable. It takes **4** arguments and an `Object` is expect to return: + +```js +{ + attrs: function callback(cell, row, rowIndex, colIndex) { ... } +} +``` + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `Object` will be the result of element HTML attributes. + +> Caution: +> If `column.classes`, `column.style`, `column.title`, `column.hidden` or `column.align` was given at the same time, property `attrs` has lower priorty and it will be overwrited: + +```js +{ + // omit... + title: true, // get higher priority + attrs: { title: 'test' } +} +``` + +## column.headerAttrs - [Object | Function] +`headerAttrs` is similiar to [`column.attrs`](#columnattrs-object-function) but it works for header column. +```js +{ + // omit... + headerAttrs: { + title: 'bar', + 'data-test': 'foo' + } +} +``` + +Additionally, customize the header attributes by a **2** arguments callback function: + +```js +{ + // omit... + headerAttrs: (column, colIndex) => ({ + // return customized HTML attribute here + }) +} +``` + +**Parameters** +* `column`: The value of current column. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +**Return value** + +A new `Object` will be the result of element headerAttrs. + +> Caution: +> Same as [column.attrs](#columnattrs-object-function), it has lower priority and will be +> overwrited when other props related to HTML attributes were given. + +## headerSortingClasses - [String | Function] + +`headerSortingClasses` allows to customize `class` for header cell when this column is sorting. + +```js +const headerSortingClasses = 'demo-sorting'; +``` + +Furthermore, it also accepts a callback which takes **4** arguments and `String` is expected to return: + +```js +const headerSortingClasses = (column, sortOrder, isLastSorting, colIndex) => { ... } +``` + +* `column`: The value of current column. +* `sortOrder`: The order of current sorting +* `isLastSorting`: Is the last one of sorted columns. +* `colIndex`: The index of the current column being processed in BootstrapTable. + +## headerSortingStyle - [Object | Function] + +It's similiar to [headerSortingClasses](#headersortingclasses-string-function). It allows to customize the style of header cell when this column is sorting. A style `Object` and `callback` are acceptable. `callback` takes **4** arguments and an `Object` is expected to return: + +```js +const sortingHeaderStyle = { + backgroundColor: 'red' +}; +``` + +## column.editable - [Bool | Function] +`column.editable` default is true, means every column is editable if you configure [`cellEdit`](./README.md#cellEdit). But you can disable some columns editable via setting `false`. + +If a callback function given, you can control the editable level as cell level: + +```js +{ + // omit... + editable: (cell, row, rowIndex, colIndex) => { + // return true or false; + } +} +``` + +## column.validator - [Function] +`column.validator` used for validate the data when cell on updating. it's should accept a callback function with following argument: +`newValue`, `row` and `column`: + +```js +{ + // omit... + validator: (newValue, row, column) => { + return ...; + } +} +``` + +The return value can be a bool or an object. If your valiation is pass, return `true` explicitly. If your valiation is invalid, return following object instead: +```js +{ + valid: false, + message: 'SOME_REASON_HERE' +} +``` + +## column.editCellStyle - [Object | Function] +You can use `column.editCellStyle` to custom the style of `` when cell editing. It like most of customizable functionality, it also accept a callback function with following params: + +**Parameters** +* `cell`: The value of current cell. +* `row`: The object of `row` being processed in the `BootstrapTable`. +* `rowIndex`: The index of the current `row` being processed in the `BootstrapTable`. +* `colIndex`: The index of the current `column` being processed in `BootstrapTable`. + +```js +{ + editCellStyle: { ... } +} +``` +Or take a callback function + +```js +{ + editCellStyle: (cell, row, rowIndex, colIndex) => { + // it is suppose to return an object + } +} +``` + +## column.editCellClasses - [String | Function] +You can use `column.editCellClasses` to add custom class on `` when cell editing. It's same as [`column.editCellStyle`](#columneditcellstyle-object-function) which also accept a callback function to able to custom your class more flexible. Following is the arguments of this callback function: `cell`, `row`, `rowIndex`, `colIndex`. + +```js +{ + editCellClasses: 'custom-class' +} +``` +Or take a callback function + +```js +{ + editCellClasses: (cell, row, rowIndex, colIndex) => { + // it is suppose to return a string + } +} +``` + +## column.filter - [Object] +Configure `column.filter` will able to setup a column level filter on the header column. Currently, `react-bootstrap-table2` support following filters: + +* Text Filter + +We have a quick example to show you how to use `column.filter`: + +```js +import { textFilter } from 'react-bootstrap-table2-filter'; + +// omit... +{ + dataField: 'price', + text: 'Product Price', + filter: textFilter() +} +``` + +For some reason of simple customization, `react-bootstrap-table2` allow you to pass some props to filter factory function. Please check [here](https://github.com/react-bootstrap-table/react-bootstrap-table2/tree/master/packages/react-bootstrap-table2-filter/README.md) for more detail tutorial. + +## column.filterValue - [Function] +Sometimes, if the cell/column value that you don't want to filter on them, you can define `filterValue` to return a actual value you wanna be filterd: + +**Parameters** +* `cell`: The value of current cell. +* `row`: The value of current row. + +**Return value** + +A final `String` value you want to be filtered. + +```js +// omit... +{ + dataField: 'price', + text: 'Product Price', + filter: textFilter(), + filterValue: (cell, row) => owners[cell] +} +``` diff --git a/docs/filter-props.md b/docs/filter-props.md new file mode 100644 index 0000000..d38666f --- /dev/null +++ b/docs/filter-props.md @@ -0,0 +1,6 @@ +--- +id: filter-props +title: Column Filter Props +--- + +**No Any Available Props Yet** \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..04de33d --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,46 @@ +--- +id: getting-started +title: Getting Started +sidebar_label: Getting Started +--- + +## Installation + +```sh +$ npm install react-bootstrap-table2 --save +``` + +## Add CSS + +> `react-bootstrap-table2` compatible with bootstrap 3 and 4 but you need to add bootstrap css in your application firstly. + +Finish above step, let's add the `react-bootstrap-table2` styles: + +```js +// es5 +require('react-bootstrap-table/dist/react-bootstrap-table2.min.css'); + +// es6 +import 'react-bootstrap-table/dist/react-bootstrap-table2.min.css'; +``` + +## Your First Table + +```js +import BootstrapTable from 'react-bootstrap-table2'; + +const products = [ ... ]; +const columns = [{ + dataField: 'id', + text: 'Product ID' +}, { + dataField: 'name', + text: 'Product Name' +}, { + dataField: 'price', + text: 'Product Price' +}]; + +export default () => + +``` diff --git a/docs/pagination-props.md b/docs/pagination-props.md new file mode 100644 index 0000000..1ef0264 --- /dev/null +++ b/docs/pagination-props.md @@ -0,0 +1,112 @@ +--- +id: pagination-props +title: Pagination Props +--- + +## Required +**NONE** + +## Optional +* [page](#paginationpage-number) +* [sizePerPage](#paginationsizeperpage-number) +* [totalSize](#paginationtotalsize-number) +* [pageStartIndex](#paginationpagestartindex-number) +* [paginationSize](#paginationpaginationsize-number) +* [sizePerPageList](#paginationsizeperpagelist-array) +* [withFirstAndLast](#paginationwithfirstandlast-bool) +* [alwaysShowAllBtns](#paginationalwaysshowallbtns-bool) +* [firstPageText](#paginationfirstpagetext-any) +* [prePageText](#paginationprepagetext-any) +* [nextPageText](#paginationnextpagetext-any) +* [lastPageText](#paginationlastpagetext-any) +* [firstPageTitle](#paginationfirstpagetitle-any) +* [prePageTitle](#paginationprepagetitle-any) +* [nextPageTitle](#paginationnextpagetitle-any) +* [lastPageTitle](#paginationlastpagetitle-any) +* [hideSizePerPage](#paginationhidesizeperpage-bool) +* [hidePageListOnlyOnePage](#paginationhidepagelistonlyonepage-bool) +* [onPageChange](#paginationonpagechange-function) +* [onSizePerPageChange](#paginationonsizeperpagechange-function) +----- + +## pagination.page - [Number] +Use `pagination.page` specify the current page when table render. + +> It's necessary value when [remote](./table-props.html#remote-bool-object) pagination is enabled. + +## pagination.sizePerPage - [Number] +Use `pagination.sizePerPage` specify the current size per page when table render. + +> It's necessary value when [remote](./table-props.html#remote-bool-object) pagination is enabled. + +## pagination.totalSize - [Number] +It's only work for [remote](./table-props.html#remote-bool-object) mode, because `react-bootstrap-table2` will never know the totally data size actually. Remeber to assign `totalSize` when you enable the remote pagination. + +## pagination.pageStartIndex - [Number] +Default is **1**, which means the first page index is start from 1. If your first page want to start from **0**, you can control it via `pageStartIndex`. + +## pagination.paginationSize - [Number] +Default is **5**, which means the size of pagination. + +## pagination.sizePerPageList - [Array] +Default size per page have **10**, **25**, **30**, **50**. You can assign a number of array to replace this default list. However, `sizePerPageList` is flexible to let you decide the text display on the dropdown list: + +```js +[ { + text: '5th', value: 5 +}, { + text: '10th', value: 10 +}, { + text: 'All', value: data.length +} ] +``` + +## pagination.withFirstAndLast - [Bool] +Default is `true`, you can disable it if you don't want to show the **"Go to first"** and **"Go to last"** page buttons. + +## pagination.alwaysShowAllBtns - [Bool] +Default is `false`, which means `react-bootstrap-table2` will hide the next or previouse page button if unnecessary. Anyway, you can still show them always via `alwaysShowAllBtns` prop. + +## pagination.firstPageText - [Any] +A quick way to specify the text on the first page button. + +## pagination.prePageText - [Any] +A quick way to specify the text on the previous page button. + +## pagination.nextPageText - [Any] +A quick way to specify the text on the next page button. + +## pagination.lastPageText - [Any] +A quick way to specify the text on the last page button. + +## pagination.firstPageTitle - [Any] +A quick way to specify the title on the first page button. + +## pagination.prePageTitle - [Any] +A quick way to specify the title on the previous page button. + +## pagination.nextPageTitle - [Any] +A quick way to specify the title on the next page button. + +## pagination.lastPageTitle - [Any] +A quick way to specify the title on the last page button. + +## pagination.hideSizePerPage - [Bool] +You can hide it :) + +## pagination.hidePageListOnlyOnePage - [Bool] +You can hide the pagination when there's only one page in table. Default is `false`. + +## pagination.onPageChange - [Function] +Accept a callback function and will be called when page changed. This callback function get below arguments: + +**Arguments** +* page +* sizePerPage + +## pagination.onSizePerPageChange - [Function] +Accept a callback function and will be called when size per page changed. This callback function get below arguments: + +**Arguments** +* page +* sizePerPage \ No newline at end of file diff --git a/docs/row-select-props.md b/docs/row-select-props.md new file mode 100644 index 0000000..78c1468 --- /dev/null +++ b/docs/row-select-props.md @@ -0,0 +1,172 @@ +--- +id: row-select-props +title: Row Selection Props +--- + +## Required +* [mode (**required**)](#selectrowmode-string) + +## Optional +* [style](#selectrowstyle-object-function) +* [classes](#selectrowclasses-string-function) +* [bgColor](#selectrowbgcolor-string-function) +* [nonSelectable)](#selectrownonselectable-array) +* [clickToSelect)](#selectrowclicktoselect-bool) +* [clickToEdit](#selectrowclicktoedit-bool) +* [onSelect](#selectrowonselect-function) +* [onSelectAll](#selectrowonselectall-function) +* [hideSelectColumn](#selectrowhideselectcolumn-bool) + +----- + +## selectRow.mode - [String] + +Specifying the selection way for `single(radio)` or `multiple(checkbox)`. If `radio` was assigned, there will be a radio button in the selection column; otherwise, the `checkbox` instead. + +### Available values +* **radio** +* **checkbox** + +Following is a quick example for single selection: + +```js +const selectRow = { + mode: 'radio' // single row selection +}; + + +``` + +## selectRow.style - [Object | Function] +`selectRow.style` allow you to have custom style on selected rows: + +```js +const selectRow = { + mode: 'checkbox', + style: { background: 'red' } +}; +``` + +If you wanna more flexible customization, `selectRow.style` also accept a function: + +```js +const selectRow = { + mode: 'checkbox', + style: (row, rowIndex) => { return ...; } +}; +``` + +## selectRow.classes - [String | Function] +`selectRow.classes` allow you to add css class on selected rows: + +```js +const selectRow = { + mode: 'checkbox', + classes: 'custom-class' +}; +``` + +If you wanna more flexible customization, `selectRow.classes` also accept a function: + +```js +const selectRow = { + mode: 'checkbox', + classes: (row, rowIndex) => { return ...; } +}; +``` + +## selectRow.bgColor - [String | Function] +A quick way to specify the backgroud color when row is selected + +```js +const selectRow = { + mode: 'checkbox', + bgColor: 'red' +}; +``` + +There's also a more good way to custom it: + +```js +const selectRow = { + mode: 'checkbox', + bgColor: (row, rowIndex) => { + return ....; // return a color code + } +}; +``` + +## selectRow.nonSelectable - [Array] +This prop allow you to restrict some rows which can not be selected by user. `selectRow.nonSelectable` accept an rowkeys array. + +```js +const selectRow = { + mode: 'checkbox', + nonSelectable: [1, 3 ,5] +}; +``` + +## selectRow.clickToSelect - [Bool] +Allow user to select row by clicking on the row. + +```js +const selectRow = { + mode: 'checkbox', + clickToSelect: true +}; +``` + +> Note: When you also enable [cellEdit](./cell-edit-props.html), the `selectRow.clickToSelect` will deactivate the functionality of cell editing. If you want to click on row to select row and edit cell simultaneously, you are suppose to enable [`selectRow.clickToEdit`](#selectrowclicktoedit-bool) + +## selectRow.clickToEdit - [Bool] +Able to click to edit cell and select row at the same time. + +```js +const selectRow = { + mode: 'checkbox', + clickToSelect: true + clickToEdit: true +}; +``` + +## selectRow.onSelect - [Function] +This callback function will be called when a row is select/unselect and pass following three arguments: +`row`, `isSelect` and `rowIndex`. + +```js +const selectRow = { + mode: 'checkbox', + onSelect: (row, isSelect, rowIndex) => { + // ... + } +}; +``` + +## selectRow.onSelectAll - [Function] +This callback function will be called when select/unselect all and it only work when you configure [`selectRow.mode`](#selectrowmode-string) as `checkbox`. + +```js +const selectRow = { + mode: 'checkbox', + onSelectAll: (isSelect, results) => { + // ... + } +}; +``` + +## selectRow.hideSelectColumn - [Bool] +Default is `false`, if you don't want to have a selection column, give this prop as `true` + +```js +const selectRow = { + mode: 'radio', + hideSelectColumn: true, + clickToSelect: true, + bgColor: 'red' +}; +``` \ No newline at end of file diff --git a/docs/table-props.md b/docs/table-props.md new file mode 100644 index 0000000..aedfa8e --- /dev/null +++ b/docs/table-props.md @@ -0,0 +1,280 @@ +--- +id: table-props +title: BootstrapTable Props +--- +## Required +* [keyField (**required**)](#keyfield-required-string) +* [data (**required**)](#data-required-array) +* [columns (**required**)](#columns-required-object) + +## Optional +* [remote](#remote-bool-object) +* [loading](#loading-bool) +* [overlay](#overlay-function) +* [caption](#caption-string-node) +* [striped](#striped-bool) +* [bordered](#bordered-bool) +* [hover](#hover-bool) +* [condensed](#condensed-bool) +* [cellEdit](#celledit-object) +* [selectRow](#selectrow-object) +* [rowStyle](#rowstyle-object-function) +* [rowClasses](#rowclasses-string-function) +* [rowEvents](#rowevents-object) +* [defaultSorted](#defaultsorted-array) +* [pagination](#pagination-object) +* [filter](#filter-object) +* [onTableChange](#ontablechange-function) + +----- + +## keyField(**required**) - [String] +Tells `react-bootstrap-table2` which column is unique. + +## data(**required**) - [Array] +Provides data for your table. It accepts a single Array object. + +## columns(**required**) - [Object] +Accepts a single Array object, please see [columns definition](./columns.md) for more detail. + +## remote - [Bool | Object] +Default is `false`, if enable `remote`, you are supposed to be handle all the table change events, like: pagination, insert, filtering etc. +This is a chance that you can connect to your remote server or database to manipulate your data. +For flexibility reason, you can control what functionality should be handled on remote via a object return: + +```js +remote={ { + filter: true, + pagination: true, + filter: true, + sort: true, + cellEdit: true +} } +``` + +In above case, only column filter will be handled on remote. + +> Note: when remote is enable, you are suppose to give [`onTableChange`](#ontablechange-function) prop on `BootstrapTable` +> It's the only way to communicate to your remote server and update table states. + +A special case for remote pagination: +```js +remote={ { pagination: true, filter: false, sort: false } } +``` + +There'r a apecial case for remote pagination, even you only specified the paignation need to handle as remote, `react-bootstrap-table2` will handle all the table changes(filter, sort etc) as remote mode, because `react-bootstrap-table2` only know the data of current page, but filtering, searching or sort need to work on overall datas. + +## loading - [Bool] +Telling if table is loading or not, for example: waiting data loading, filtering etc. It's **only** valid when [`remote`](#remote-bool-object) is enabled. +When `loading` is `true`, `react-bootstrap-table2` will attend to render a overlay on table via [`overlay`](#overlay-function) prop, if [`overlay`](#overlay-function) prop is not given, `react-bootstrap-table2` will ignore the overlay rendering. + +## overlay - [Function] +`overlay` accept a factory funtion which should returning a higher order component. By default, `react-bootstrap-table2-overlay` can be a good option for you: + +```sh +$ npm install react-bootstrap-table2-overlay +``` +```js +import overlayFactory from 'react-bootstrap-table2-overlay'; + + +``` + +Actually, `react-bootstrap-table2-overlay` is depends on [`react-loading-overlay`](https://github.com/derrickpelletier/react-loading-overlay) and `overlayFactory` just a factory function and you can pass any props which available for `react-loading-overlay`: + +```js +overlay={ overlayFactory({ spinner: true, background: 'rgba(192,192,192,0.3)' }) } +``` + +## caption - [String | Node] +Same as HTML [caption tag](https://www.w3schools.com/TAgs/tag_caption.asp), you can set it as String or a React JSX. + +## striped - [Bool] +Same as bootstrap `.table-striped` class for adding zebra-stripes to a table. +## bordered - [Bool] +Same as bootstrap `.table-bordered` class for adding borders to a table and table cells. +## hover - [Bool] +Same as bootstrap `.table-hover` class for adding mouse hover effect (grey background color) on table rows. +## condensed - [Bool] +Same as bootstrap `.table-condensed` class for making a table more compact by cutting cell padding in half. + +## cellEdit - [Object] +Makes table cells editable, please see [cellEdit definition](./cell-edit.md) for more detail. + +## selectRow - [Object] +Makes table rows selectable, please see [selectRow definition](./row-selection.md) for more detail. + +## rowStyle = [Object | Function] +Custom the style of table rows: + +```js + +``` + +This prop also accept a callback function for flexible to custom row style: + +```js +const rowStyle = (row, rowIndex) => { + return { ... }; +}; + + +``` + +## rowClasses = [String | Function] +Custom the style of table rows: + +```js + +``` + +This prop also accept a callback function for flexible to custom row style: + +```js +const rowClasses = (row, rowIndex) => { + return 'custom-row-class'; +}; + + +``` + +## rowEvents - [Object] +Custom the events on row: + +```js +const rowEvents = { + onClick: (e) => { + .... + } +}; + +``` + +## defaultSorted - [Array] +`defaultSorted` accept an object array which allow you to define the default sort columns when first render. + +```js +const defaultSorted = [{ + dataField: 'name', // if dataField is not match to any column you defined, it will be ignored. + order: 'desc' // desc or asc +}]; +``` + +## pagination - [Object] +`pagination` allow user to render a pagination panel on the bottom of table. But pagination funcitonality is separated from core of `react-bootstrap-table2` so that you are suppose to install `react-bootstrap-table2-paginator` additionaly. + +```sh +$ npm install react-bootstrap-table2-paginator --save +``` + +After installation of `react-bootstrap-table2-paginator`, you can enable pagination on `react-bootstrap-table2` easily: + +```js +import paginator from 'react-bootstrap-table2-paginator'; + +// omit... + + +``` + +`paginator` is a function actually and allow to pass some pagination options, following we list all the available options: + +```js +paginator({ + page, // Specify the current page. It's necessary when remote is enabled + sizePerPage, // Specify the size per page. It's necessary when remote is enabled + totalSize, // Total data size. It's necessary when remote is enabled + pageStartIndex: 0, // first page will be 0, default is 1 + paginationSize: 3, // the pagination bar size, default is 5 + sizePerPageList: [ { + text: '5', value: 5 + }, { + text: '10', value: 10 + }, { + text: 'All', value: products.length + } ], // A numeric array is also available: [5, 10]. the purpose of above example is custom the text + withFirstAndLast: false, // hide the going to first and last page button + alwaysShowAllBtns: true, // always show the next and previous page button + firstPageText: 'First', // the text of first page button + prePageText: 'Prev', // the text of previous page button + nextPageText: 'Next', // the text of next page button + lastPageText: 'Last', // the text of last page button + nextPageTitle: 'Go to next', // the title of next page button + prePageTitle: 'Go to previous', // the title of previous page button + firstPageTitle: 'Go to first', // the title of first page button + lastPageTitle: 'Go to last', // the title of last page button + hideSizePerPage: true, // hide the size per page dorpdown + hidePageListOnlyOnePage: true, // hide pagination bar when only one page, default is false + onPageChange: (page, sizePerPage) => {}, // callback function when page was changing + onSizePerPageChange: (sizePerPage, page) => {}, // callback function when page size was changing +}) +``` + +## filter - [Object] +`filter` allow user to filter data by column. However, filter funcitonality is separated from core of `react-bootstrap-table2` so that you are suppose to install `react-bootstrap-table2-filter` firstly. + +```sh +$ npm install react-bootstrap-table2-filter --save +``` + +After installation of `react-bootstrap-table2-filter`, you can configure filter on `react-bootstrap-table2` easily: + +```js +import filterFactory, { textFilter } from 'react-bootstrap-table2-filter'; + +// omit... +const columns = [ { + dataField: 'id', + text: 'Production ID' +}, { + dataField: 'name', + text: 'Production Name', + filter: textFilter() // apply text filter +}, { + dataField: 'price', + text: 'Production Price' +} ]; + +``` + +## onTableChange - [Function] +This callback function will be called when [`remote`](#remote-bool-object) enabled only. + +```js +const onTableChange = (type, newState) => { + // handle any data change here +} + +``` + +There's only two arguments will be passed to `onTableChange`: `type` and `newState`: + +`type` is tell you what kind of functionality to trigger this table's change: available values at the below: + +* `filter` +* `pagination` +* `sort` +* `cellEdit` + +Following is a shape of `newState` + +```js +{ + page, // newest page + sizePerPage, // newest sizePerPage + sortField, // newest sort field + sortOrder, // newest sort order + filters, // an object which have current filter status per column + data, // when you enable remote sort, you may need to base on data to sort if data is filtered/searched + cellEdit: { // You can only see this prop when type is cellEdit + rowId, + dataField, + newValue + } +} +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..3432c41 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,7 @@ +--- +id: usage +title: document number 2 +--- + +This is a link to [another document.](/docs/en/doc3.md) +This is a link to an [external page.](http://www.example.com)