https://github.com/reactabular/searchtabular
Search utilities (MIT)
https://github.com/reactabular/searchtabular
Last synced: 9 months ago
JSON representation
Search utilities (MIT)
- Host: GitHub
- URL: https://github.com/reactabular/searchtabular
- Owner: reactabular
- License: mit
- Created: 2016-10-23T18:31:46.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-05-22T17:39:09.000Z (over 7 years ago)
- Last Synced: 2025-04-30T08:11:33.190Z (9 months ago)
- Language: JavaScript
- Size: 176 KB
- Stars: 5
- Watchers: 2
- Forks: 17
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](http://travis-ci.org/reactabular/searchtabular) [](https://www.bithound.io/github/reactabular/searchtabular) [](https://codecov.io/gh/reactabular/searchtabular)
# Searchtabular - Search utilities
Searchtabular comes with search helpers. It consists of search algorithms that can be applied to the rows. Just like with sorting, you have to apply it to the rows just before rendering. A column is considered searchable in case it has a unique `property` defined.
> If you want advanced filters including date, number, and boolean, see [searchtabular-antd](https://www.npmjs.com/package/searchtabular-antd).
## API
The search API consists of three parts. Out of these `search.multipleColumns` and `search.matches` are the most useful ones for normal usage. If the default search strategies aren't enough, it's possible to implement more as long as you follow the same interface.
```javascript
import * as search from 'searchtabular';
// Or you can cherry-pick
import { multipleColumns } from 'searchtabular';
import { multipleColumns as searchMultipleColumns } from 'searchtabular';
```
### Search
**`search.multipleColumns({ castingStrategy: , columns: [], query: {: }, strategy: , transform: })([]) => []`**
This is the highest level search function available. It expects `rows` and `columns` in the same format the `Table` uses. `query` object describes column specific search queries.
It uses `infix` strategy underneath although it is possible to change it. By default it matches in a case **insensitive** manner. If you want case sensitive behavior, pass `a => a`(identity function) as `transform`.
It will cast everything but arrays to a string by default. If you want a custom casting behavior, pass a custom function to `castingStrategy(value, column)`. It should return the cast result.
**`search.singleColumn({ castingStrategy: , columns: [], searchColumn: , query: , strategy: , transform: })([]) => []`**
This is a more specialized version of `search.multipleColumns`. You can use it to search a specific column through `searchColumn` and `query`.
### Matchers
**`search._columnMatches({ query: , castingStrategy: , column: , row: , strategy: , transform: }) => `**
This is a function that can be used to figure out all column specific matches. It is meant only for **internal usage** of the library.
When dealing with strings:
**`search.matches({ value: , query: , strategy: , transform: }) => [{ startIndex: , length: }]`**
Returns an array with the matches.
When dealing with arrays:
**`search.matches({ value: , query: [], strategy: , transform: }) => [[{ startIndex: , length: }], ...]`**
Returns a sparse array with the same shape as the original query. If there was a match for an item, it will have the same shape as the string version above, otherwise the array will have a hole in that location.
This function returns matches against the given value and query. This is particularly useful with highlighting.
### Strategies
**`search.strategies.infix(queryTerm: ) => { evaluate(searchText: ) => , matches(searchText) => [{ startIndex: , length: }]`**
Search uses `infix` strategy by default. This means it will match even if the result is in the middle of a `searchText`.
The strategies operate in two passes - evaluation and matching. The evaluation pass allows us to implement perform fast boolean check on whether or not a search will match. Matching gives exact results.
**`search.strategies.prefix(queryTerm: ) => { evaluate(searchText: ) => , matches(searchText) => [{ startIndex: , length: }]`**
`prefix` strategy matches from the start.
## Highlighting Search Results
To make it possible to highlight search results per column, there's a specific `highlightCell` formatter.
## How to Use?
The general workflow goes as follows:
1. Set up a `Search` control that outputs a query in `{: }` format. If `` is `all`, then the search will work against all columns. Otherwise it will respect the exact columns set. You'll most likely want to use either `reactabular-search-field` or `reactabular-search-columns` (or both) for this purpose or provide an implementation of your own if you are not using Reactabular.
2. Before rendering the rows, perform `search.multipleColumns({ columns, query })(rows)`. This will filter the rows based on the passed `rows`, `columns` definition, and `query`. A lazy way to do this is to filter at `render()` although you can do it elsewhere too to optimize rendering.
3. Pass the filtered rows to `Table`.
To use it, you'll first you have to annotate your rows using `highlighter`. It attaches a structure like this there:
```javascript
_highlights: {
demo: [{ startIndex: 0, length: 4 }]
}
```
**Example:**
```jsx
/*
import React from 'react';
import { compose } from 'redux';
import * as Table from 'reactabular-table';
import * as resolve from 'table-resolver';
import * as search from 'searchtabular';
*/
class HighlightTable extends React.Component {
constructor(props) {
super(props);
this.state = {
searchColumn: 'all',
query: {},
columns: [
{
header: {
label: 'Name'
},
children: [
{
property: 'name.first',
header: {
label: 'First Name'
},
cell: {
formatters: [search.highlightCell]
}
},
{
property: 'name.last',
header: {
label: 'Last Name'
},
cell: {
formatters: [search.highlightCell]
}
}
]
},
{
property: 'age',
header: {
label: 'Age'
},
cell: {
formatters: [search.highlightCell]
}
}
],
rows: [
{
id: 100,
name: {
first: 'Adam',
last: 'West'
},
age: 10
},
{
id: 101,
name: {
first: 'Brian',
last: 'Eno'
},
age: 43
},
{
id: 103,
name: {
first: 'Jake',
last: 'Dalton'
},
age: 33
},
{
id: 104,
name: {
first: 'Jill',
last: 'Jackson'
},
age: 63
}
]
};
}
render() {
const { searchColumn, columns, rows, query } = this.state;
const resolvedColumns = resolve.columnChildren({ columns });
const resolvedRows = resolve.resolve({
columns: resolvedColumns,
method: resolve.nested
})(rows);
const searchedRows = compose(
search.highlighter({
columns: resolvedColumns,
matches: search.matches,
query
}),
search.multipleColumns({
columns: resolvedColumns,
query
}),
)(resolvedRows);
return (
Search
this.setState({ searchColumn })}
onChange={query => this.setState({ query })}
/>
);
}
}
```
## Components
`searchtabular` provides a couple of convenience components listed below.
### Searching Columns
`searchtabular.Columns` is a single component you can inject within a table header to allow searching per column. It expects `columns` and `onChange` handler. The latter is used to update the search query based on the search protocol.
## How to Use?
Consider the example below.
**Example:**
```jsx
/*
import React from 'react';
import * as Table from 'reactabular-table';
import * as resolve from 'table-resolver';
import * as search from 'searchtabular';
*/
class SearchColumnsTable extends React.Component {
constructor(props) {
super(props);
this.state = {
query: {}, // Search query
columns: [
{
header: {
label: 'Name'
},
children: [
{
property: 'name.first',
header: {
label: 'First Name'
}
},
{
property: 'name.last',
header: {
label: 'Last Name'
}
}
]
},
{
property: 'age',
header: {
label: 'Age'
}
}
],
rows: [
{
id: 100,
name: {
first: 'Adam',
last: 'West'
},
age: 10
},
{
id: 101,
name: {
first: 'Brian',
last: 'Eno'
},
age: 43
},
{
id: 103,
name: {
first: 'Jake',
last: 'Dalton'
},
age: 33
},
{
id: 104,
name: {
first: 'Jill',
last: 'Jackson'
},
age: 63
}
]
};
}
render() {
const { columns, query, rows } = this.state;
const resolvedColumns = resolve.columnChildren({ columns });
const resolvedRows = resolve.resolve({
columns: resolvedColumns,
method: resolve.nested
})(rows);
const searchedRows = search.multipleColumns({
columns: resolvedColumns,
query
})(resolvedRows);
return (
this.setState({ query })}
/>
);
}
}
```
> To disable search on a particular column, set `filterable: false` on a column you want to disable.
### Searching Through a Single Field
`searchtabular.Field` provides a search control with a column listing and an input.
`searchtabular.Field` also supports custom component overrides for the column `` and `` field.
It is on you to couple the `onChange` events to the target fields rendered within your custom components.
## How to Use?
Consider the example below.
**Example:**
```jsx
/*
import React from 'react';
import * as Table from 'reactabular-table';
import * as resolve from 'table-resolver';
import * as search from 'searchtabular';
import { CustomField, CustomSelect } from './path/to/your/component';
*/
class SearchTable extends React.Component {
constructor(props) {
super(props);
this.state = {
searchColumn: 'all',
query: {}, // Search query
columns: [
{
header: {
label: 'Name'
},
children: [
{
property: 'name.first',
header: {
label: 'First Name'
}
},
{
property: 'name.last',
header: {
label: 'Last Name'
}
}
]
},
{
property: 'age',
header: {
label: 'Age'
}
}
],
rows: [
{
id: 100,
name: {
first: 'Adam',
last: 'West'
},
age: 10
},
{
id: 101,
name: {
first: 'Brian',
last: 'Eno'
},
age: 43
},
{
id: 103,
name: {
first: 'Jake',
last: 'Dalton'
},
age: 33
},
{
id: 104,
name: {
first: 'Jill',
last: 'Jackson'
},
age: 63
}
]
};
}
render() {
const { searchColumn, columns, rows, query } = this.state;
const resolvedColumns = resolve.columnChildren({ columns });
const resolvedRows = resolve.resolve({
columns: resolvedColumns,
method: resolve.nested
})(rows);
const searchedRows = search.multipleColumns({
columns: resolvedColumns,
query
})(resolvedRows);
return (
Search
this.setState({ searchColumn })}
onChange={query => this.setState({ query })}
components={{
filter: CustomField,
select: CustomSelect,
props: {
filter: {
className: 'custom-textfield',
placeholder: 'Refine Results'
},
select: {
className: 'custom-select'
}
}
}}
/>
);
}
}
const CustomField = (props, classNames) => ;
const CustomSelect = ({ options, onChange, classNames }) => (
{ options.map(({ key, name, value }) => (
- {name}
)
) }
);
```
## License
MIT. See LICENSE for details.