Skip to content

Commit 1817ed4

Browse files
fzaninottofzaninotto
committed
Improve doc
1 parent 536b813 commit 1817ed4

File tree

3 files changed

+48
-117
lines changed

3 files changed

+48
-117
lines changed

‎docs/FilterList.md

+45-111
Original file line numberDiff line numberDiff line change
@@ -5,130 +5,64 @@ title: "The FilterList Component"
55

66
# `<FilterList>`
77

8+
An alternative UI to the Filter Button/Form Combo is the FilterList Sidebar. Similar to what users usually see on e-commerce websites, it's a panel with many simple filters that can be enabled and combined using the mouse.
9+
810
![Filter Sidebar](./img/filter-sidebar.gif)
911

10-
An alternative UI to the Filter Button/Form Combo is the FilterList Sidebar. Similar to what users usually see on e-commerce websites, it's a panel with many simple filters that can be enabled and combined using the mouse. The user experience is better than the Button/Form Combo, because the filter values are explicit, and it doesn't require typing anything in a form. But it's a bit less powerful, as only filters with a finite set of values (or intervals) can be used in the `<FilterList>`.
12+
The user experience is better than the Button/Form Combo, because the filter values are explicit, and it doesn't require typing anything in a form. But it's a bit less powerful, as only filters with a finite set of values (or intervals) can be used in the `<FilterList>`.
1113

1214
## Usage
1315

14-
The `<FilterList>` component expects a list of `<FilterListItem>` as children. Each `<FilterListItem>` defines a filter `label` and a `value`, which is merged with the current filter value when enabled by the user. Here is an example usage for a list of customers:
16+
Use the `<FilterList>` component in a sidebar for the `<List>` view. It expects a list of `<FilterListItem>` as children. Each `<FilterListItem>` defines a filter `label` and a `value`, which is merged with the current filter value when enabled by the user.
17+
18+
For instance, here is a filter sidebar for a post list, allowing users to filter on two fields:
1519

1620
{% raw %}
1721
```jsx
18-
import AccessTimeIcon from '@mui/icons-material/AccessTime';
19-
import MonetizationOnIcon from '@mui/icons-material/MonetizationOnOutlined';
22+
import { SavedQueriesList, FilterLiveSearch, FilterList, FilterListItem } from 'react-admin';
23+
import { Card, CardContent } from '@mui/material';
2024
import MailIcon from '@mui/icons-material/MailOutline';
21-
import LocalOfferIcon from '@mui/icons-material/LocalOfferOutlined';
22-
import { FilterList, FilterListItem } from 'react-admin';
23-
import {
24-
endOfYesterday,
25-
startOfWeek,
26-
subWeeks,
27-
startOfMonth,
28-
subMonths,
29-
} from 'date-fns';
30-
31-
import segments from '../segments/data';
32-
33-
const LastVisitedFilter = () => (
34-
<FilterList label="Last visited" icon={<AccessTimeIcon />}>
35-
<FilterListItem
36-
label="Today"
37-
value={{
38-
last_seen_gte: endOfYesterday().toISOString(),
39-
last_seen_lte: undefined,
40-
}}
41-
/>
42-
<FilterListItem
43-
label="This week"
44-
value={{
45-
last_seen_gte: startOfWeek(new Date()).toISOString(),
46-
last_seen_lte: undefined,
47-
}}
48-
/>
49-
<FilterListItem
50-
label="Last week"
51-
value={{
52-
last_seen_gte: subWeeks(startOfWeek(new Date()), 1).toISOString(),
53-
last_seen_lte: startOfWeek(new Date()).toISOString(),
54-
}}
55-
/>
56-
<FilterListItem
57-
label="This month"
58-
value={{
59-
last_seen_gte: startOfMonth(new Date()).toISOString(),
60-
last_seen_lte: undefined,
61-
}}
62-
/>
63-
<FilterListItem
64-
label="Last month"
65-
value={{
66-
last_seen_gte: subMonths(startOfMonth(new Date()),1).toISOString(),
67-
last_seen_lte: startOfMonth(new Date()).toISOString(),
68-
}}
69-
/>
70-
<FilterListItem
71-
label="Earlier"
72-
value={{
73-
last_seen_gte: undefined,
74-
last_seen_lte: subMonths(startOfMonth(new Date()),1).toISOString(),
75-
}}
76-
/>
77-
</FilterList>
78-
);
79-
const HasOrderedFilter = () => (
80-
<FilterList
81-
label="Has ordered"
82-
icon={<MonetizationOnIcon />}
83-
>
84-
<FilterListItem
85-
label="True"
86-
value={{
87-
nb_commands_gte: 1,
88-
nb_commands_lte: undefined,
89-
}}
90-
/>
91-
<FilterListItem
92-
label="False"
93-
value={{
94-
nb_commands_gte: undefined,
95-
nb_commands_lte: 0,
96-
}}
97-
/>
98-
</FilterList>
99-
);
100-
const HasNewsletterFilter = () => (
101-
<FilterList
102-
label="Has newsletter"
103-
icon={<MailIcon />}
104-
>
105-
<FilterListItem
106-
label="True"
107-
value={{ has_newsletter: true }}
108-
/>
109-
<FilterListItem
110-
label="False"
111-
value={{ has_newsletter: false }}
112-
/>
113-
</FilterList>
114-
);
115-
const SegmentFilter = () => (
116-
<FilterList
117-
label="Segment"
118-
icon={<LocalOfferIcon />}
119-
>
120-
{segments.map(segment => (
121-
<FilterListItem
122-
label={segment.name}
123-
key={segment.id}
124-
value={{ groups: segment.id }}
125-
/>
126-
))}
127-
</FilterList>
25+
import CategoryIcon from '@mui/icons-material/LocalOffer';
26+
27+
export const PostFilterSidebar = () => (
28+
<Card sx={{ order: -1, mr: 2, mt: 9, width: 200 }}>
29+
<CardContent>
30+
<SavedQueriesList />
31+
<FilterLiveSearch >
32+
<FilterList label="Subscribed to newsletter" icon={<MailIcon />}>
33+
<FilterListItem label="Yes" value={{ has_newsletter: true }} />
34+
<FilterListItem label="No" value={{ has_newsletter: false }} />
35+
</FilterList>
36+
<FilterList label="Category" icon={<CategoryIcon />}>
37+
<FilterListItem label="Tests" value={{ category: 'tests' }} />
38+
<FilterListItem label="News" value={{ category: 'news' }} />
39+
<FilterListItem label="Deals" value={{ category: 'deals' }} />
40+
<FilterListItem label="Tutorials" value={{ category: 'tutorials' }} />
41+
</FilterList>
42+
</CardContent>
43+
</Card>
12844
);
12945
```
13046
{% endraw %}
13147

48+
Add this component to the list view using [the `<List aside>` prop](./List.md#aside):
49+
50+
```jsx
51+
import { PostFilterSidebar } from './PostFilterSidebar';
52+
53+
export const PostList = () => (
54+
<List aside={<PostFilterSidebar />}>
55+
...
56+
</List>
57+
);
58+
```
59+
60+
**Tip**: The `<Card sx>` prop in the `PostFilterSidebar` component above is here to put the sidebar on the left side of the screen, instead of the default right side.
61+
62+
A more sophisticated example is the filter sidebar for the visitors list visible in the screencast at the beginning of this page. The code for this example is available in the [react-admin repository](https://github.com/marmelab/react-admin/blob/master/examples/demo/src/visitors/VisitorListAside.tsx).
63+
64+
**Tip**: In a Filter List sidebar, you can use [the `<FilterLiveSearch>` component](./FilterLiveSearch.md) to add a search input at the top of the sidebar, and [the `<SavedQueriesList>` component](./SavedQueriesList.md) to add a list of saved queries.
65+
13266
`<FilterList>` accepts 3 props:
13367

13468
* [`children`](#children), which must be a list of `<FilterListItem>`

‎docs/FilteringTutorial.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ export const PostList = () => (
203203
);
204204
```
205205

206-
**Tip**: the `<Card sx>` prop in the `PostFilterSidebar` component above is here to put the sidebar on the left side of the screen, instead of the default right side.
206+
**Tip**: The `<Card sx>` prop in the `PostFilterSidebar` component above is here to put the sidebar on the left side of the screen, instead of the default right side.
207207

208208
Check [the `<FilterList>` documentation](./FilterList.md) for more information.
209209

‎docs/SavedQueriesList.md

+2-5
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ title: "The SavedQueriesList Component"
77

88
![Filter Sidebar With SavedQueriesList](./img/SavedQueriesList.gif)
99

10-
`<SavedQueriesList>` renders a list of filters saved by the end user (and kept in [the Store](./Store.md)). It is a complement to `<FilterList>` sections for the filter sidebar
10+
`<SavedQueriesList>` renders a list of filters saved by the end user (and kept in [the Store](./Store.md)). It is a complement to `<FilterList>` sections for [the filter sidebar](./FilteringTutorial.md#the-filterlist-sidebar).
1111

1212
## Usage
1313

@@ -17,7 +17,7 @@ import {
1717
FilterListItem,
1818
List,
1919
Datagrid
20-
+ SavedQueriesList
20+
+ SavedQueriesList
2121
} from 'react-admin';
2222
import { Card, CardContent } from '@mui/material';
2323

@@ -82,6 +82,3 @@ const SongList = props => (
8282
```
8383
{% endraw %}
8484

85-
## API
86-
87-
[`<SavedQueriesList>`]: https://github.com/marmelab/react-admin/blob/master/packages/ra-ui-materialui/src/list/filter/SavedQueriesList.tsx

0 commit comments

Comments
 (0)