diff --git a/docs/Search.md b/docs/Search.md new file mode 100644 index 00000000000..216acf04116 --- /dev/null +++ b/docs/Search.md @@ -0,0 +1,192 @@ +--- +layout: default +title: "The Search Component" +--- + +# `` + +This [Enterprise Edition](https://marmelab.com/ra-enterprise) component, part of [`ra-search`](https://marmelab.com/ra-enterprise/modules/ra-search), lets user do a site-wide search via a smart Omnibox. + +![ra-search](https://marmelab.com/ra-enterprise/modules/assets/ra-search-demo.gif) + +`` renders a global search input. It's designed to be integrated into the top ``. + +It relies on the `dataProvider` to provide a `search()` method, so you can use it with any search engine (Lucene, ElasticSearch, Solr, Algolia, Google Cloud Search, and many others). And if you don't have a search engine, no problem! `` can also do the search across several resources via parallel `dataProvider.getList()` queries. + +## Usage + +Include the `` component inside a custom `` component: + +{% raw %} +```jsx +// in src/MyAppBar.jsx +import { AppBar } from "react-admin"; +import { Typography } from "@mui/material"; +import { Search } from "@react-admin/ra-search"; + +export const MyAppbar = (props) => ( + + + + +); +``` +{% endraw %} + +Include that AppBar in [a custom layout component](./Layout.md): + +```jsx +// in src/MyLayout.jsx +import { Layout } from "react-admin"; +import { MyAppbar } from "./MyAppBar"; + +export const MyLayout = (props) => ; +``` + +Finally, include that custom layout in the ``. You'll also need to setup the ì18nProvider`, as the `ra-search` package comes with some new translations. + +```jsx +// in src/Admin.ts +import { Admin } from "react-admin"; + +import { MyLayout } from "./MyLayout"; + +export const App = () => ( + + // ... + +); +``` + +Your `dataProvider` should support the `search()` method. Check [the `ra-search` documentation](https://marmelab.com/ra-enterprise/modules/ra-search) to learn its i,nput and output interface, as well as tricks to use `dataProvider.search()` without a search engine. + +## Props + + +| Prop | Required | Type | Default | Description | +| ----------- | -------- | ------------------ | -------- | ------------------------------------------------------------------ | +| `children` | Optional | `ReactNode` | `` | The search result renderer | +| `options` | Optional | `object` | - | The search options (see details below) | +| `wait` | Optional | `number` | 500 | The delay of debounce for the search to launch after typing in ms. | +| `color` | Optional | `'light' | 'dark'` | 'light' | The color mode for the input, applying light or dark background. | + +The `options` object can contain the following keys: + +- `targets`: `string[]` An array of the indices on which to perform the search. Defaults to an empty array. +- `historySize`: `number` The max number of search texts kept in the history. Default is 5. +- `{any}`: `{any}` Any custom option to pass to the search engine. + +## Customizing The Result Items + +By default, `` displays the results in ``, which displays each results in a ``. So rendering `` without children is equivalent to rendering: + +```jsx +const MySearch = () => ( + + + + + +); +``` + +`` renders the `content.label` and `content.description` for each result. You can customize what it renders by providing a function as the `label` and the `description` props. This function takes the search result as a parameter and must return a React element. + +For instance: + +```jsx +import { + Search, + SearchResultsPanel, + SearchResultItem, +} from '@react-admin/ra-search'; + +const MySearch = () => ( + + + ( + <> + {record.type === 'artists' ? ( + + ) : ( + + )} + {record.content.label} + + )} + /> + + +); +``` + +You can also completely replace the search result item component: + +```jsx +import { Search, SearchResultsPanel } from '@react-admin/ra-search'; + +const MySearchResultItem = ({ data, onClose }) => ( +
  • + + {data.content.label} + +

    {data.content.description}

    +
    • +); + +const MySearch = () => ( + + + + + +); +``` + +## Customizing the Entire Search Results + +Pass a custom React element as a child of `` to customize the appearance of the search results. This can be useful e.g. to customize the results grouping, or to arrange search results differently. + +`ra-search` renders the `` inside a `SearchContext`. You can use the `useSearchResultContext` hook to read the search results, as follows: + +```jsx +import { Search, useSearchResult } from '@react-admin/ra-search'; + +const MySearch = props => ( + + + +); + +const CustomSearchResultsPanel = () => { + const { data, onClose } = useSearchResult(); + + return ( +
      + {data.map(searchResult => ( +
    • + + {searchResult.content.label} + +

      {searchResult.content.description}

      +
      • + ))} +
    + ); +}; +``` diff --git a/docs/Theming.md b/docs/Theming.md index 0fd8c6bb3ae..0f0f07efc28 100644 --- a/docs/Theming.md +++ b/docs/Theming.md @@ -343,7 +343,7 @@ const App = () => ( ); ``` -## Light and Dark Themes +## Using A Dark Theme MUI ships two base themes: light and dark. React-admin uses the light one by default. To use the dark theme, create a custom theme object with a `mode: 'dark'` palette, and pass it as the `` prop: @@ -365,35 +365,36 @@ const App = () => ( ![Dark theme](./img/dark-theme.png) -If you want to let users choose between the light and dark themes, check the next section. +## Letting Users Choose The Theme -## Changing the Theme Programmatically +The `` component lets users switch from light to dark mode, and persists that choice by leveraging the [store](./Store.md). -You can define several themes (usually a light and a dark theme), and let the user choose between them. +![Dark Mode support](./img/ToggleThemeButton.gif) -React-admin provides the `useTheme` hook to read and update the theme programmatically. It uses the same syntax as `useState`: +You can add the `` to a custom App Bar: ```jsx -import { defaultTheme, useTheme } from 'react-admin'; -import { Button } from '@mui/material'; +import * as React from 'react'; +import { defaultTheme, Layout, AppBar, ToggleThemeButton } from 'react-admin'; +import { createTheme, Box, Typography } from '@mui/material'; -const lightTheme = defaultTheme; -const darkTheme = { - ...defaultTheme, - palette: { - mode: 'dark', - }, -}; +const darkTheme = createTheme({ + palette: { mode: 'dark' }, +}); -const ThemeToggler = () => { - const [theme, setTheme] = useTheme(); +const MyAppBar = props => ( + + + + + + +); - return ( - - ); -} +const MyLayout = props => ; ``` ## Conditional Formatting @@ -760,50 +761,6 @@ export default MyLayout; ``` {% endraw %} -## Adding a Breadcrumb - -The `` component is part of `ra-navigation`, an [Enterprise Edition](https://marmelab.com/ra-enterprise) module. It displays a breadcrumb based on a site structure that you can override at will. - -```jsx -import * as React from 'react'; -import { - AppLocationContext, - Breadcrumb, - ResourceBreadcrumbItems, -} from '@react-admin/ra-navigation'; -import { Admin, Resource, Layout } from 'react-admin'; - -import PostList from './PostList'; -import PostEdit from './PostEdit'; -import PostShow from './PostShow'; -import PostCreate from './PostCreate'; - -const MyLayout = ({ children, ...props }) => ( - - - - - - {children} - - -); - -const App = () => ( - - - -); -``` - -Check [the `ra-navigation` documentation](https://marmelab.com/ra-enterprise/modules/ra-navigation) for more details. - ## Customizing the AppBar Content By default, the react-admin `` component displays the page title. You can override this default by passing children to `` - they will replace the default title. And if you still want to include the page title, make sure you include an element with id `react-admin-title` in the top bar (this uses [React Portals](https://reactjs.org/docs/portals.html)). @@ -921,38 +878,6 @@ To make it easier to customize, we export some components and hooks used by the - ``: An `IconButton` used to toggle the ``. - `useSidebarState`: A hook that returns the sidebar open state and a function to toggle it. Used internally by ``. -## Adding Dark Mode Support - -The `` component lets users switch from light to dark mode, and persists that choice by leveraging the [store](./Store.md). - -![Dark Mode support](./img/ToggleThemeButton.gif) - -You can add the `` to a custom App Bar: - -```jsx -import * as React from 'react'; -import { defaultTheme, Layout, AppBar, ToggleThemeButton } from 'react-admin'; -import { createTheme, Box, Typography } from '@mui/material'; - -const darkTheme = createTheme({ - palette: { mode: 'dark' }, -}); - -const MyAppBar = props => ( - - - - - - -); - -const MyLayout = props => ; -``` - ## Using a Custom Menu By default, React-admin uses the list of `` components passed as children of `` to build a menu to each resource with a `list` component. If you want to reorder, add or remove menu items, for instance to link to non-resources pages, you have to provide a custom `` component to your `Layout`. diff --git a/docs/navigation.html b/docs/navigation.html index e2dad4eb445..7565d061dd3 100644 --- a/docs/navigation.html +++ b/docs/navigation.html @@ -202,6 +202,7 @@
  • <MultiLevelMenu>
  • <IconMenu>
  • <Breadcrumb>
    • +
  • <Search>
  • Buttons
  • Confirm