Merge pull request #5638 from marmelab/saved-queries

[Doc] Add mention of saved queries in List chapter
marmelab · Dec 8, 2020 · 7edc001 · 7edc001
2 parents 12a40fb + c186d9a
commit 7edc001
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 0 deletions.
diff --git a/docs/List.md b/docs/List.md
@@ -799,6 +799,7 @@ React-admin proposes several UI components to let users see and modify filters,
 - The `<FilterList>` Sidebar
   - [Usage](#the-filterlist-sidebar)
   - [Full-Text Search](#live-search)
+- [Saved Queries: Let Users Save Filter And Sort](#saved-queries-let-users-save-filter-and-sort)
 - [Building A Custom Filter](#building-a-custom-filter)
 
 ### Filter Query Parameter
@@ -1142,6 +1143,97 @@ const FilterSidebar = () => (
 );
 ```
 
+### Saved Queries: Let Users Save Filter And Sort
+
+[![Saved Queries in FilterList](https://marmelab.com/ra-enterprise/modules/assets/ra-preferences-SavedQueriesList.gif)](https://marmelab.com/ra-enterprise/modules/assets/ra-preferences-SavedQueriesList.gif)
+
+Saved Queries are an [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> feature letting users save a combination of filters and sort parameters into a new, personal filter. Saved queries persist between sessions, so users can find their custom queries even after closing and reopening the admin. Saved queries are available both for the `<Filter>` Button/Form combo and for the `<FilterList>` Sidebar:
+
+- `<FilterWithSave>` is a drop-in replacement for react-admin's `<Filter>` component
+
+```diff
+import {
+-   Filter,
+    SelectInput,
+    DateInput,
+    List,
+    Datagrid,
+    TextField,
+    NumberField,
+    DateField
+} from 'react-admin';
++import { FilterWithSave } from '@react-admin/ra-preferences';
+
+const SongFilter: FC = props => (
+-   <Filter {...props}>
++   <FilterWithSave {...props}>
+        <SelectInput
+            choices={[
+                { id: 'Apple', name: 'Apple' },
+                { id: 'Atlantic', name: 'Atlantic' },
+                { id: 'Capitol', name: 'Capitol' },
+                { id: 'Chess', name: 'Chess' },
+                { id: 'Columbia', name: 'Columbia' },
+                { id: 'DGC', name: 'DGC' },
+                { id: 'London', name: 'London' },
+                { id: 'Tamla', name: 'Tamla' },
+            ]}
+            source="recordCompany"
+        />
+        <DateInput source="released_gte" label="Released after" />
+        <DateInput source="released_lte" label="Released before" />
+-   </Filter>
++   </FilterWithSave>
+);
+
+const SongList: FC<Props> = props => (
+    <List {...props} filters={<SongFilter />}>
+        <Datagrid rowClick="edit">
+            <TextField source="title" />
+            <TextField source="artist" />
+            <TextField source="writer" />
+            <TextField source="producer" />
+            <TextField source="recordCompany" />
+            <NumberField source="rank" />
+            <DateField source="released" />
+        </Datagrid>
+    </List>
+);
+```
+
+- `<SavedFilterList>` is a complement to `<FilterList>` sections for the filter sidebar
+
+```diff
+import { FilterList, FilterListItem, List, Datagrid } from 'react-admin';
+import { Card, CardContent } from '@material-ui/core';
+
++import { SavedQueriesList } from '@react-admin/ra-preferences';
+
+const SongFilterSidebar: FC = () => (
+    <Card>
+        <CardContent>
++           <SavedQueriesList />
+            <FilterList label="Record Company" icon={<BusinessIcon />}>
+                ...
+            </FilterList>
+            <FilterList label="Released" icon={<DateRangeeIcon />}>
+               ...
+            </FilterList>
+        </CardContent>
+    </Card>
+);
+
+const SongList: FC<Props> = props => (
+    <List {...props} aside={<SongFilterSidebar />}>
+        <Datagrid>
+            ...
+        </Datagrid>
+    </List>
+);
+```
+
+For mode details about Saved Queries, check  the [`ra-preferences` module](https://marmelab.com/ra-enterprise/modules/ra-preferences#savedquerieslist-and-filterwithsave-store-user-queries-in-preferences) in React-Admin Enterprise Edition. 
+
 ### Building a Custom Filter
 
 ![Filters with submit button](./img/filter_with_submit.gif)

diff --git a/docs/Reference.md b/docs/Reference.md
@@ -58,6 +58,7 @@ title: "Reference"
 * [`<FilterList>`](./List.md#the-filterlist-sidebar)
 * [`<FilterListItem>`](./List.md#the-filterlist-sidebar)
 * [`<FilterLiveSearch>`](./List.md#live-search)
+* [`<FilterWithSave>`](https://marmelab.com/ra-enterprise/modules/ra-preferences#savedquerieslist-and-filterwithsave-store-user-queries-in-preferences)<img class="icon" src="./img/premium.svg" />
 * [`<FormDataConsumer>`](./Inputs.md#linking-two-inputs)
 * [`<FormTab>`](./CreateEdit.md#the-tabbedform-component)
 * [`<FunctionField>`](./Fields.md#functionfield)
@@ -104,6 +105,7 @@ title: "Reference"
 * [`<RichTextInput>`](./Inputs.md#richtextinput)
 * [`<RowForm>`](https://marmelab.com/ra-enterprise/modules/ra-editable-datagrid#rowform)<img class="icon" src="./img/premium.svg" />
 * `<SaveButton>`
+* [`<SavedFilterList>`](https://marmelab.com/ra-enterprise/modules/ra-preferences#savedquerieslist-and-filterwithsave-store-user-queries-in-preferences)<img class="icon" src="./img/premium.svg" />
 * `<SearchInput>`
 * [`<SelectArrayInput>`](./Inputs.md#selectarrayinput)
 * [`<SelectColumnsButton>`](https://marmelab.com/ra-enterprise/modules/ra-preferences#selectcolumnsbutton-store-datagrid-columns-in-preferences)<img class="icon" src="./img/premium.svg" />