Skip to content

Commit fde7049

Browse files
fhlavacfhlavac
committed
feat(filters): Document DataView filters
1 parent 970d33b commit fde7049

File tree

3 files changed

+130
-4
lines changed

3 files changed

+130
-4
lines changed

‎packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ source: react
1111
# If you use typescript, the name of the interface to display props for
1212
# These are found through the sourceProps function provided in patternfly-docs.source.js
1313
sortValue: 4
14-
propComponents: ['DataViewToolbar', 'DataViewTableBasic', 'DataViewTableTree']
14+
propComponents: ['DataViewToolbar', 'DataViewTableBasic', 'DataViewTableTree', 'DataViewTrTree', 'DataViewTrObject']
1515
sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md
1616
---
1717
import { Button, EmptyState, EmptyStateActions, EmptyStateBody, EmptyStateFooter, EmptyStateHeader, EmptyStateIcon } from '@patternfly/react-core';
@@ -26,7 +26,7 @@ import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynami
2626

2727
The **data view toolbar** component renders a default opinionated data view toolbar above or below the data section.
2828

29-
Data view toolbar can contain a `pagination`, `bulkSelect`, `actions` or other children content passed. The preffered way of passing children toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component.
29+
Data view toolbar can contain a `pagination`, `bulkSelect`, `filters`, `actions` or other children content passed. The preffered way of passing children toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component.
3030

3131
### Basic toolbar example
3232

‎packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/FiltersExample.tsx

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
import React, { useMemo } from 'react';
2+
import { Pagination } from '@patternfly/react-core';
3+
import { BrowserRouter, useSearchParams } from 'react-router-dom';
4+
import { useDataViewFilters, useDataViewPagination } from '@patternfly/react-data-view/dist/dynamic/Hooks';
5+
import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
6+
import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
7+
import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
8+
import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters';
9+
import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter';
10+
11+
const perPageOptions = [
12+
{ title: '5', value: 5 },
13+
{ title: '10', value: 10 }
14+
];
15+
16+
interface Repository {
17+
name: string;
18+
branch: string | null;
19+
prs: string | null;
20+
workspaces: string;
21+
lastCommit: string;
22+
}
23+
24+
interface RepositoryFilters {
25+
name: string,
26+
branch: string
27+
}
28+
29+
const repositories: Repository[] = [
30+
{ name: 'Repository one', branch: 'Branch one', prs: 'Pull request one', workspaces: 'Workspace one', lastCommit: 'Timestamp one' },
31+
{ name: 'Repository two', branch: 'Branch two', prs: 'Pull request two', workspaces: 'Workspace two', lastCommit: 'Timestamp two' },
32+
{ name: 'Repository three', branch: 'Branch three', prs: 'Pull request three', workspaces: 'Workspace three', lastCommit: 'Timestamp three' },
33+
{ name: 'Repository four', branch: 'Branch four', prs: 'Pull request four', workspaces: 'Workspace four', lastCommit: 'Timestamp four' },
34+
{ name: 'Repository five', branch: 'Branch five', prs: 'Pull request five', workspaces: 'Workspace five', lastCommit: 'Timestamp five' },
35+
{ name: 'Repository six', branch: 'Branch six', prs: 'Pull request six', workspaces: 'Workspace six', lastCommit: 'Timestamp six' }
36+
];
37+
38+
const columns = [ 'Name', 'Branch', 'Pull requests', 'Workspaces', 'Last commit' ];
39+
40+
const ouiaId = 'LayoutExample';
41+
42+
const MyTable: React.FunctionComponent = () => {
43+
const [ searchParams, setSearchParams ] = useSearchParams();
44+
const pagination = useDataViewPagination({ perPage: 5 });
45+
const { page, perPage } = pagination;
46+
const { filters, onSetFilters, clearAllFilters } = useDataViewFilters<RepositoryFilters>({ initialFilters: { name: '', branch: '' }, searchParams, setSearchParams });
47+
48+
const pageRows = useMemo(() => repositories
49+
.filter(item => (!filters.name || item.name?.toLocaleLowerCase().includes(filters.name?.toLocaleLowerCase())) && (!filters.branch || item.branch?.toLocaleLowerCase().includes(filters.branch?.toLocaleLowerCase())))
50+
.slice((page - 1) * perPage, ((page - 1) * perPage) + perPage)
51+
.map(item => Object.values(item)), [ page, perPage, filters ]);
52+
53+
return (
54+
<DataView>
55+
<DataViewToolbar
56+
ouiaId='LayoutExampleHeader'
57+
clearAllFilters = {clearAllFilters}
58+
pagination={
59+
<Pagination
60+
perPageOptions={perPageOptions}
61+
itemCount={repositories.length}
62+
{...pagination}
63+
/>
64+
}
65+
filters={
66+
<DataViewFilters onChange={(_e, values) => onSetFilters(values)} values={filters}>
67+
<DataViewTextFilter filterId="name" title='Name' placeholder='Filter by name' />
68+
<DataViewTextFilter filterId="branch" title='Branch' placeholder='Filter by branch' />
69+
</DataViewFilters>
70+
}
71+
/>
72+
<DataViewTable aria-label='Repositories table' ouiaId={ouiaId} columns={columns} rows={pageRows} />
73+
<DataViewToolbar
74+
ouiaId='LayoutExampleFooter'
75+
pagination={
76+
<Pagination
77+
isCompact
78+
perPageOptions={perPageOptions}
79+
itemCount={repositories.length}
80+
{...pagination}
81+
/>
82+
}
83+
/>
84+
</DataView>
85+
);
86+
}
87+
88+
export const BasicExample: React.FunctionComponent = () => (
89+
<BrowserRouter>
90+
<MyTable/>
91+
</BrowserRouter>
92+
)

‎packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,18 @@ source: react
1111
# If you use typescript, the name of the interface to display props for
1212
# These are found through the sourceProps function provided in patternfly-docs.source.js
1313
sortValue: 3
14+
propComponents: ['DataViewFilters', 'DataViewTextFilter']
1415
sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md
1516
---
1617
import { useMemo } from 'react';
17-
import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks';
18+
import { BrowserRouter, useSearchParams } from 'react-router-dom';
19+
import { useDataViewPagination, useDataViewSelection, useDataViewFilters } from '@patternfly/react-data-view/dist/dynamic/Hooks';
1820
import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
1921
import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect';
2022
import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
2123
import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
22-
import { BrowserRouter, useSearchParams } from 'react-router-dom';
24+
import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters';
25+
import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter';
2326

2427
This is a list of functionality you can use to manage data displayed in the **data view**.
2528

@@ -84,3 +87,34 @@ The `useDataViewSelection` hook manages the selection state of the data view.
8487
```js file="./SelectionExample.tsx"
8588

8689
```
90+
91+
# Filters
92+
Enables filtering of data records in the data view and displays the applied filter chips.
93+
94+
### Toolbar usage
95+
The data view toolbar can include a set of filters by passing a React node to the `filters` property. You can use predefined components `DataViewFilters` and `DataViewTextFilter` to customize and handle filtering directly in the toolbar. The `DataViewFilters` is a wrapper allowing conditional filtering using multiple attributes. If you need just a single filter, you can use `DataViewTextFilter` or a different filter component alone. Props of these filter components are listed at the bottom of this page.
96+
97+
You can decide between passing `value` and `onChange` event to every filter separately or pass `values` and `onChange` to the `DataViewFilters` wrapper which make them available to its children. Props directly passed to child filters have a higher priority than the "inherited" ones.
98+
99+
### Filters state
100+
101+
The `useDataViewFilters` hook manages the filter state of the data view. It allows you to define default filter values, synchronize filter state with URL parameters, and handle filter changes efficiently.
102+
103+
**Initial values:**
104+
- `initialFilters` object with default filter values
105+
- optional `searchParams` object for managing URL-based filter state
106+
- optional `setSearchParams` function to update the URL when filters are modified
107+
108+
The `useDataViewFilters` hook works well with the React Router library to support URL-based filtering. Alternatively, you can manage filter state in the URL using `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If no URL parameters are provided, the filter state is managed internally.
109+
110+
**Return values:**
111+
- `filters` object representing the current filter values
112+
- `onSetFilters` function to update the filter state
113+
- `clearAllFilters` function to reset all filters to their initial values
114+
115+
### Filtering example
116+
This example demonstrates the setup and usage of filters within the data view. It includes text filters for different attributes, the ability to clear all filters, and persistence of filter state in the URL.
117+
118+
```js file="./FiltersExample.tsx"
119+
120+
```

0 commit comments

Comments
 (0)