From b4c411708218dbda5956f67b506e71c8fa8a847d Mon Sep 17 00:00:00 2001 From: erwanMarmelab Date: Mon, 27 May 2024 17:40:15 +0200 Subject: [PATCH] [Doc] Update OSS doc for ra-navigation v5 --- docs/Breadcrumb.md | 68 ++++++++++-------------------------- docs/ContainerLayout.md | 50 ++++++++++++++++++++------ docs/useDefineAppLocation.md | 4 +-- 3 files changed, 59 insertions(+), 63 deletions(-) diff --git a/docs/Breadcrumb.md b/docs/Breadcrumb.md index 32bc6f566af..1095d46a708 100644 --- a/docs/Breadcrumb.md +++ b/docs/Breadcrumb.md @@ -28,9 +28,9 @@ Create a custom layout component containing the `` component. For ex import { AppLocationContext, Breadcrumb } from '@react-admin/ra-navigation'; import { Layout } from 'react-admin'; -export const MyLayout = ({ children, ...rest }) => ( +export const MyLayout = ({ children }) => ( - + {children} @@ -88,24 +88,9 @@ With this setup, the breadcrumb on the post pages will use the `title` field of - "Posts / Lorem ipsum" on the Post Show page with id = 1 - "Posts / Create" on the Post Creation page -If your app has a home or dashboard page, set the `` prop to display the dashboard as the root of the breadcrumb: +The Breadcrumb component will automatically detect if your app has a home or dashboard page, thanks to `react-admin`'s `useHasDashboard` hook. -```jsx -// in src/MyLayout.jsx -import { AppLocationContext, Breadcrumb } from '@react-admin/ra-navigation'; -import { Layout } from 'react-admin'; - -export const MyLayout = ({ children, ...rest }) => ( - - - - {children} - - -); -``` - -With this setup, the breadcrumb on the post pages now renders as: +With a dashboard, the breadcrumb on the post pages now renders as: - "🏠️ / Posts" on the Post List page - "🏠️ / Posts / Lorem ipsum" on the Post Edition page with id = 1 @@ -140,8 +125,6 @@ If, however, you are using the default `` component from `react-admin`, | Prop | Required | Type | Default | Description | | -------------- | -------- | ------------------ | ------- | ------------------------------------------------------------------------------------ | | `children` | Optional | `ReactNode` | - | The Breadcrumb Items to be rendered. | -| `dashboard` | Optional | `ReactNode` | - | The dashboard component, used to determine if the Admin has a dashboard. | -| `hasDashboard` | Optional | boolean | - | Alternative to `dashboard`. Set to `true` to add a dashboard item to the breadcrumb. | | `separator` | Optional | string or function | ' / ' | The character user as separator | | `sx` | Optional | `SxProps` | - | Style overrides, powered by MUI System | @@ -204,9 +187,9 @@ import { Layout } from 'react-admin'; import { MyBreadcrumb } from './MyBreadcrumb'; -export const MyLayout = ({ children, ...rest }) => ( +export const MyLayout = ({ children }) => ( - + {children} @@ -471,7 +454,7 @@ It is convenient for customizing the dashboard item label. ```tsx const MyBreadcrumbCustomHome = () => ( - + @@ -489,7 +472,7 @@ import { visuallyHidden } from '@mui/utils'; import CabinIcon from '@mui/icons-material/Cabin'; const MyBreadcrumbCustomHome = () => ( - + @@ -507,26 +490,11 @@ const MyBreadcrumbCustomHome = () => ( **Tip:** It's a good practice to include a visually hidden placeholder ('Dashboard' in this example) for screen readers when using an icon as label. -## Using A Dashboard As The Root +## Admins With A Dashboard -If the app has a home page defined via the [``](./Admin.md#dashboard) prop, you can automatically set the root of the Breadcrumb to this page by setting the `hasDashboard` prop in the `` component: +If the app has a home page defined via the [``](./Admin.md#dashboard) prop, the Breadcrumb will automatically detect it and set the root of the Breadcrumb to this page. -```jsx -// in src/MyLayout.jsx -import { AppLocationContext, Breadcrumb } from '@react-admin/ra-navigation'; -import { Layout } from 'react-admin'; - -export const MyLayout = ({ children, ...rest }) => ( - - - - {children} - - -); -``` - -By doing this, the breadcrumb will now show respectively: +The breadcrumb will show respectively: - "🏠️ / Posts" on the Post List page - "🏠️ / Posts / Show #1" on the Post Show page with id = 1 @@ -535,7 +503,7 @@ By doing this, the breadcrumb will now show respectively: **Tip:** Even though it is rendered as a 'home' icon (🏠️), the dashboard breadcrumb item also contains the hidden placeholder text 'Dashboard', for screen readers. If you want to customize this text, e.g. to rename "Dashboard" to "Home", provide a [custom translation](https://marmelab.com/react-admin/Translation.html) for the `ra.page.dashboard` message. -If you want to customize the dashboard breadcrumb item label, e.g. to rename "Dashboard" to "Home", provide a [custom translation](./Translation.md) for the `ra.page.dashboard` message. +If you want to provide your own label for the dashboard breadcrumb item (either a string or a React component), you can use the [``](#breadcrumbdashboarditem) component. Remember to pass `hasDashboard={false}` to `` to avoid having two Home links. ## Adding Custom Pages @@ -596,9 +564,9 @@ import { Layout } from 'react-admin'; import { MyBreadcrumb } from './MyBreadcrumb'; -export const MyLayout = ({ children, ...rest }) => ( +export const MyLayout = ({ children }) => ( - + {children} @@ -615,7 +583,7 @@ import React from 'react'; import { AppLocationContext, Breadcrumb } from '@react-admin/ra-navigation'; import { Admin, Resource, Layout, useCreatePath, List } from 'react-admin'; -const MyBreadcrumb = ({ children, ...props }) => { +const MyBreadcrumb = () => { const createPath = useCreatePath(); return ( @@ -640,9 +608,9 @@ const MyBreadcrumb = ({ children, ...props }) => { ); }; -const MyLayout = ({ children, ...rest }) => ( - - +const MyLayout = ({ children }) => ( + + {children} diff --git a/docs/ContainerLayout.md b/docs/ContainerLayout.md index 83c8779b008..05d01ccee81 100644 --- a/docs/ContainerLayout.md +++ b/docs/ContainerLayout.md @@ -47,7 +47,12 @@ If you want to use a different color for the AppBar, or to make it sticky, pass import { ContainerLayout, Header } from '@react-admin/ra-navigation'; const myAppBar =
; -const MyLayout = props => ; + +const MyLayout = ({ children }) => ( + + {children} + +); ``` ## `fixed` @@ -57,7 +62,11 @@ If you prefer to design for a fixed set of sizes instead of trying to accommodat ```jsx import { ContainerLayout } from '@react-admin/ra-navigation'; -const MyLayout = props => ; +const MyLayout = ({ children }) => ( + + {children} + +); ``` ## `maxWidth` @@ -67,7 +76,11 @@ This prop allows to set the maximum width of the content [``](https:/ ```jsx import { ContainerLayout } from '@react-admin/ra-navigation'; -const MyLayout = props => ; +const MyLayout = ({ children }) => ( + + {children} + +); ``` ## `menu` @@ -98,7 +111,11 @@ const Menu = () => ( ); -const MyLayout = props => } />; +const MyLayout = ({ children }) => ( + }> + {children} + +); const CustomPage = () => { useDefineAppLocation('custom'); @@ -127,13 +144,14 @@ The `sx` prop allows to customize the style of the layout, and the underlying co ```jsx import { ContainerLayout } from '@react-admin/ra-navigation'; -const MyLayout = props => ( +const MyLayout = ({ children }) => ( + > + {children} + ); ``` {% endraw %} @@ -152,7 +170,11 @@ const toolbar = ( ); -const MyLayout = props => ; +const MyLayout = ({ children }) => ( + + {children} + +); ``` ## `userMenu` @@ -195,8 +217,10 @@ const CustomUserMenu = () => ( ); -export const MyLayout = props => ( - } /> +export const MyLayout = ({ children }) => ( + }> + {children} + ); ``` {% endraw %} @@ -233,7 +257,11 @@ import { ContainerLayout } from '@react-admin/ra-navigation'; import { Menu } from './Menu'; -const MyLayout = props => } />; +const MyLayout = ({ children }) => ( + }> + {children} + +); const App = () => ( diff --git a/docs/useDefineAppLocation.md b/docs/useDefineAppLocation.md index 2a74551752a..8c4c769e2ee 100644 --- a/docs/useDefineAppLocation.md +++ b/docs/useDefineAppLocation.md @@ -93,9 +93,9 @@ import { Layout } from 'react-admin'; import { MyBreadcrumb } from './MyBreadcrumb'; -export const MyLayout = ({ children, ...rest }) => ( +export const MyLayout = ({ children }) => ( - + {children}