Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Doc] Add documentation for the Menu component #7907

Merged
merged 4 commits into from
Jun 29, 2022
Merged

[Doc] Add documentation for the Menu component #7907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
126cd64
[doc] Document Layout menu instead of the sidebar prop
fzaninotto Jun 28, 2022
66e3293
Document Menu component
fzaninotto Jun 28, 2022
4172f5e
typo check
fzaninotto Jun 28, 2022
277a920
Apply suggestions from code review
fzaninotto Jun 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 12 additions & 23 deletions docs/Admin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,54 +313,43 @@ React-admin uses the list of `<Resource>` components passed as children of `<Adm
If you want to add or remove menu items, for instance to link to non-resources pages, you can create your own menu component:

```jsx
// in src/Menu.js
// in src/MyMenu.js
import * as React from 'react';
import { createElement } from 'react';
import { useMediaQuery } from '@mui/material';
import { MenuItemLink, useResourceDefinitions, useSidebarState } from 'react-admin';
import { Menu, useResourceDefinitions } from 'react-admin';
import LabelIcon from '@mui/icons-material/Label';

const Menu = ({ onMenuClick }) => {
export const MyMenu = () => {
const isXSmall = useMediaQuery(theme => theme.breakpoints.down('xs'));
const [open] = useSidebarState();
const resources = useResourceDefinitions();

return (
<div>
<Menu>
{Object.keys(resources).map(name => (
<MenuItemLink
<Menu.Item
key={name}
to={`/${name}`}
primaryText={resources[name].options && resources[name].options.label || name}
leftIcon={createElement(resources[name].icon)}
onClick={onMenuClick}
sidebarIsOpen={open}
/>
))}
<MenuItemLink
to="/custom-route"
primaryText="Miscellaneous"
leftIcon={<LabelIcon />}
onClick={onMenuClick}
sidebarIsOpen={open}
/>
</div>
<Menu.Item to="/custom-route" primaryText="Miscellaneous" leftIcon={<LabelIcon />} />
</Menu>
);
}

export default Menu;
};
```

**Tip**: Note the `MenuItemLink` component. It must be used to avoid unwanted side effects in mobile views. It supports a custom text and icon (which must be a MUI `<SvgIcon>`).
**Tip**: `<Menu.Item>` must be used to avoid unwanted side effects in mobile views. It supports a custom text and icon (which must be a MUI `<SvgIcon>`).

Then, pass it to the `<Admin>` component as the `menu` prop:

```jsx
// in src/App.js
import Menu from './Menu';
import { MyMenu } from './Menu';

const App = () => (
<Admin menu={Menu} dataProvider={simpleRestProvider('http://path.to.my.api')}>
<Admin menu={MyMenu} dataProvider={simpleRestProvider('http://path.to.my.api')}>
// ...
</Admin>
);
Expand Down Expand Up @@ -410,7 +399,7 @@ const App = () => (
);
```

Your custom layout can simply extend the default `<Layout>` component if you only want to override the appBar, the menu, the notification component, or the error page. For instance:
Your custom layout can simply extend [the default `<Layout>` component](./Layout.md) if you only want to override the appBar, the menu, the notification component, or the error page. For instance:

```jsx
// in src/MyLayout.js
Expand Down
67 changes: 51 additions & 16 deletions docs/Layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@ title: "The Layout Component"

The default react-admin layout renders a horizontal app bar at the top, a navigation menu on the side, and the main content in the center.

![standard layout](./img/layout-component.webp)
![standard layout](./img/layout-component.gif)

In addition, the layout renders the menu as a dropdown on mobile.

![layout responsive](./img/layout-responsive.gif)

React-admin lets you override the app layout using [the `<Admin layout>` prop](./Admin.md#layout). You can use any component you want as layout ; but if you just need to tweak the default layout, you can use the `<Layout>` component.

Expand All @@ -20,9 +24,8 @@ Create a custom layout overriding some of the components of the default layout:
import { Layout } from 'react-admin';

import { MyAppBar } from './MyAppBar';
import { MySidebar } from './MySidebar';

export const MyLayout = props => <Layout {...props} appBar={MyAppBar} sidebar={MySidebar} />;
export const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
```

Then pass this custom layout to the `<Admin>` component:
Expand All @@ -47,17 +50,25 @@ const App = () => (
| `appBar` | Optional | `Component` | - | A React component rendered at the top of the layout |
| `className` | Optional | `string` | - | Passed to the root `<div>` component |
| `error` | Optional | `Component` | - | A React component rendered in the content area in case of error |
| `sidebar` | Optional | `Component` | - | A React component rendered at the side of the screen |
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even if the sidebar prop exists, I see no reason to use it, so let's make it a private API. menu, on the other side, is the preferred way to set a custom menu, so it should be documented.

| `menu` | Optional | `Component` | - | A React component rendered at the side of the screen |
| `sx` | Optional | `SxProps` | - | Style overrides, powered by MUI System |

`<Layout>` accepts 4 more props, but react-admin sets them at runtime based on the `<Admin>` props:
React-admin injects more props at runtime based on the `<Admin>` props:

* `dashboard`: The dashboard component. Used to enable the dahboard link in the menu
* `menu`: A React component rendered as the sidebar content
* `title`: The default page tile, enreder in the AppBar
* `children`: The main content of the page

Any value set for these props in a custom layout will be ignored.
Any value set for these props in a custom layout will be ignored. That's why you're supposed to pass down the props when creating a layout based on `<Layout>`:

```jsx
// in src/MyLayout.js
import { Layout } from 'react-admin';

import { MyAppBar } from './MyAppBar';

export const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
```

## `appBar`

Expand Down Expand Up @@ -197,23 +208,47 @@ export const MyError = ({
};
```

## `sidebar`

Lets you override the sidebar.
## `menu`

Lets you override the menu.

```jsx
// in src/MyLayout.js
import * as React from 'react';
// in src/Layout.js
import { Layout } from 'react-admin';

import { MySidebar } from './MySidebar';
import { MyMenu } from './MyMenu';

const MyLayout = (props) => <Layout {...props} sidebar={MySidebar} />;
export const Layout = (props) => <Layout {...props} menu={MyMenu} />;
```

export default MyLayout;
You can create a custom menu component using [react-admin's `<Menu>` component](./Menu.md):

```jsx
// in src/MyMenu.js
import * as React from 'react';
import { Menu } from 'react-admin';
import BookIcon from '@mui/icons-material/Book';
import ChatBubbleIcon from '@mui/icons-material/ChatBubble';
import PeopleIcon from '@mui/icons-material/People';
import LabelIcon from '@mui/icons-material/Label';

export const MyMenu = () => (
<Menu>
<Menu.DashboardItem />
<Menu.Item to="/posts" primaryText="Posts" leftIcon={<BookIcon />}/>
<Menu.Item to="/comments" primaryText="Comments" leftIcon={<ChatBubbleIcon />}/>
<Menu.Item to="/users" primaryText="Users" leftIcon={<PeopleIcon />}/>
<Menu.Item to="/custom-route" primaryText="Miscellaneous" leftIcon={<LabelIcon />}/>
</Menu>
);
```

But you don't have to use react-admin's `<Menu>` component. In fact, the `<Layout menu>` component can render anything you like, e.g. using [MUI's `<Menu>` component](https://mui.com/material-ui/react-menu/).

**Tip**: If you need a multi-level menu, or a Mega Menu opening panels with custom content, check out [the `ra-navigation`<img class="icon" src="./img/premium.svg" /> module](https://marmelab.com/ra-enterprise/modules/ra-navigation) (part of the [Enterprise Edition](https://marmelab.com/ra-enterprise))

![MegaMenu and Breadcrumb](https://marmelab.com/ra-enterprise/modules/assets/ra-multilevelmenu-categories.gif)

## `sx`: CSS API

Pass an `sx` prop to customize the style of the main component and the underlying elements.
Expand All @@ -236,7 +271,7 @@ This property accepts the following subclasses:

To override the style of `<Layout>` using the [MUI style overrides](https://mui.com/customization/theme-components/), use the `RaLayout` key.

**Tip**: If you need to override global styles (like the default font size or family), you should [write a custom theme](./Theming.md#theming) rather than override the `<Layiyt sx>` prop. And if you need to tweak the default layout to add a right column or move the menu to the top, you're probably better off [writing your own layout component](./Theming.md#layout-from-scratch).
**Tip**: If you need to override global styles (like the default font size or family), you should [write a custom theme](./Theming.md#theming) rather than override the `<Layout sx>` prop. And if you need to tweak the default layout to add a right column or move the menu to the top, you're probably better off [writing your own layout component](./Theming.md#layout-from-scratch).

## Adding A Custom Context

Expand Down
Loading