From 546cb4e0769164fb3c192183dcb7d395bbdb3d3e Mon Sep 17 00:00:00 2001 From: ggascoigne Date: Thu, 5 Dec 2019 22:18:48 -0800 Subject: [PATCH] put useFilters docs in correct file (#1723) --- docs/api/useFilters.md | 96 +++++++++++++++++++++++++++++++++++++++++ docs/api/useSortBy.md | 97 ------------------------------------------ 2 files changed, 96 insertions(+), 97 deletions(-) create mode 100644 docs/api/useFilters.md diff --git a/docs/api/useFilters.md b/docs/api/useFilters.md new file mode 100644 index 0000000..b6e9f78 --- /dev/null +++ b/docs/api/useFilters.md @@ -0,0 +1,96 @@ +# `useFilters` + +- Plugin Hook +- Optional + +`useFilters` is the hook that implements **row filtering**. + +### Table Options + +The following options are supported via the main options object passed to `useTable(options)` + +- `state.filters: Object` + - Must be **memoized** + - An object of columnId's and their corresponding filter values. This information is stored in state since the table is allowed to manipulate the filter through user interaction. +- `initialState.filters` + - Identical to the `state.filters` option above +- `manualFilters: Bool` + - Enables filter detection functionality, but does not automatically perform row filtering. + - Turn this on if you wish to implement your own row filter outside of the table (eg. server-side or manual row grouping/nesting) +- `disableFilters: Bool` + - Disables filtering for every column in the entire table. +- `defaultCanFilter: Bool` + - Optional + - Defaults to `false` + - If set to `true`, all columns will be filterable, regardless if they have a valid `accessor` +- `filterTypes: Object` + - Must be **memoized** + - Allows overriding or adding additional filter types for columns to use. If a column's filter type isn't found on this object, it will default to using the built-in filter types. + - For more information on filter types, see Filtering +- `getResetFiltersDeps: Function(instance) => [...useEffectDependencies]` + - Optional + - Defaults to `false` + - If set, the dependencies returned from this function will be used to determine when the effect to reset the `filters` state is fired. + - To disable, set to `false` + - For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes) + +### Column Options + +The following options are supported on any `Column` object passed to the `columns` options in `useTable()` + +- `Filter: Function | React.Component => JSX` + - **Required** + - Receives the table instance and column model as props + - Must return valid JSX + - This function (or component) is used to render this column's filter UI, eg. +- `disableFilters: Bool` + - Optional + - If set to `true`, will disable filtering for this column +- `defaultCanFilter: Bool` + - Optional + - Defaults to `false` + - If set to `true`, this column will be filterable, regardless if it has a valid `accessor` +- `filter: String | Function` + - Optional + - Defaults to `text` + - The resolved function from the this string/function will be used to filter the this column's data. + - If a `string` is passed, the function with that name located on either the custom `filterTypes` option or the built-in filtering types object will be used. If + - If a `function` is passed, it will be used directly. + - For more information on filter types, see Filtering + - If a **function** is passed, it must be **memoized** + +### Instance Properties + +The following values are provided to the table `instance`: + +- `rows: Array` + - An array of **filtered** rows. +- `preFilteredRows: Array` + - The array of rows **used right before filtering**. + - Among many other use-cases, these rows are directly useful for building option lists in filters, since the resulting filtered `rows` do not contain every possible option. +- `setFilter: Function(columnId, filterValue) => void` + - An instance-level function used to update the filter value for a specific column. +- `setAllFilters: Function(filtersObject) => void` + - An instance-level function used to update the values for **all** filters on the table, all at once. + +### Column Properties + +The following properties are available on every `Column` object returned by the table instance. + +- `canFilter: Bool` + - Denotes whether a column is filterable or not depending on if it has a valid accessor/data model or is manually disabled via an option. +- `setFilter: Function(filterValue) => void` + - A column-level function used to update the filter value for this column +- `filterValue: any` + - The current filter value for this column, resolved from the table state's `filters` object +- `preFilteredRows: Array` + - The array of rows that were originally passed to this columns filter **before** they were filtered. + - This array of rows can be useful if building faceted filter options. +- `filteredRows: Array` + - The resulting array of rows received from this columns filter **after** they were filtered. + - This array of rows can be useful if building faceted filter options. + +### Example + +- [Source](https://github.com/tannerlinsley/react-table/tree/master/examples/filtering) +- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering) diff --git a/docs/api/useSortBy.md b/docs/api/useSortBy.md index c23b3a8..62c938c 100644 --- a/docs/api/useSortBy.md +++ b/docs/api/useSortBy.md @@ -125,100 +125,3 @@ The following properties are available on every `Column` object returned by the - [Source](https://github.com/tannerlinsley/react-table/tree/master/examples/sorting) - [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/sorting) - -# `useFilters` - -- Plugin Hook -- Optional - -`useFilters` is the hook that implements **row filtering**. - -### Table Options - -The following options are supported via the main options object passed to `useTable(options)` - -- `state.filters: Object` - - Must be **memoized** - - An object of columnId's and their corresponding filter values. This information is stored in state since the table is allowed to manipulate the filter through user interaction. -- `initialState.filters` - - Identical to the `state.filters` option above -- `manualFilters: Bool` - - Enables filter detection functionality, but does not automatically perform row filtering. - - Turn this on if you wish to implement your own row filter outside of the table (eg. server-side or manual row grouping/nesting) -- `disableFilters: Bool` - - Disables filtering for every column in the entire table. -- `defaultCanFilter: Bool` - - Optional - - Defaults to `false` - - If set to `true`, all columns will be filterable, regardless if they have a valid `accessor` -- `filterTypes: Object` - - Must be **memoized** - - Allows overriding or adding additional filter types for columns to use. If a column's filter type isn't found on this object, it will default to using the built-in filter types. - - For more information on filter types, see Filtering -- `getResetFiltersDeps: Function(instance) => [...useEffectDependencies]` - - Optional - - Defaults to `false` - - If set, the dependencies returned from this function will be used to determine when the effect to reset the `filters` state is fired. - - To disable, set to `false` - - For more information see the FAQ ["How do I stop my table state from automatically resetting when my data changes?"](./faq#how-do-i-stop-my-table-state-from-automatically-resetting-when-my-data-changes) - -### Column Options - -The following options are supported on any `Column` object passed to the `columns` options in `useTable()` - -- `Filter: Function | React.Component => JSX` - - **Required** - - Receives the table instance and column model as props - - Must return valid JSX - - This function (or component) is used to render this column's filter UI, eg. -- `disableFilters: Bool` - - Optional - - If set to `true`, will disable filtering for this column -- `defaultCanFilter: Bool` - - Optional - - Defaults to `false` - - If set to `true`, this column will be filterable, regardless if it has a valid `accessor` -- `filter: String | Function` - - Optional - - Defaults to `text` - - The resolved function from the this string/function will be used to filter the this column's data. - - If a `string` is passed, the function with that name located on either the custom `filterTypes` option or the built-in filtering types object will be used. If - - If a `function` is passed, it will be used directly. - - For more information on filter types, see Filtering - - If a **function** is passed, it must be **memoized** - -### Instance Properties - -The following values are provided to the table `instance`: - -- `rows: Array` - - An array of **filtered** rows. -- `preFilteredRows: Array` - - The array of rows **used right before filtering**. - - Among many other use-cases, these rows are directly useful for building option lists in filters, since the resulting filtered `rows` do not contain every possible option. -- `setFilter: Function(columnId, filterValue) => void` - - An instance-level function used to update the filter value for a specific column. -- `setAllFilters: Function(filtersObject) => void` - - An instance-level function used to update the values for **all** filters on the table, all at once. - -### Column Properties - -The following properties are available on every `Column` object returned by the table instance. - -- `canFilter: Bool` - - Denotes whether a column is filterable or not depending on if it has a valid accessor/data model or is manually disabled via an option. -- `setFilter: Function(filterValue) => void` - - A column-level function used to update the filter value for this column -- `filterValue: any` - - The current filter value for this column, resolved from the table state's `filters` object -- `preFilteredRows: Array` - - The array of rows that were originally passed to this columns filter **before** they were filtered. - - This array of rows can be useful if building faceted filter options. -- `filteredRows: Array` - - The resulting array of rows received from this columns filter **after** they were filtered. - - This array of rows can be useful if building faceted filter options. - -### Example - -- [Source](https://github.com/tannerlinsley/react-table/tree/master/examples/filtering) -- [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-table/tree/master/examples/filtering)