Skip to content

Commit 27bbe8a

Browse files
fzaninottofzaninotto
authored
Merge pull request #10528 from marmelab/doc/backport_HorizontalMenu_doc
[Doc] Add `HorizontalMenu` doc
2 parents 428c840 + 4966c04 commit 27bbe8a

File tree

6 files changed

+268
-5
lines changed

6 files changed

+268
-5
lines changed

‎docs/ContainerLayout.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,9 @@ const MyLayout = ({ children }) => (
8585

8686
## `menu`
8787

88-
By default, `<ContainerLayout>` renders one menu item per resource in the admin. To reorder the menu, omit resources, or add custom pages, pass a custom menu element to the `menu` prop. This element should be [a `<HorizontalMenu>` component](#horizontalmenu) with `<HorizontalMenu.Item>` children. Each child should have a `value` corresponding to the [application location](https://react-admin-ee.marmelab.com/documentation/ra-navigation#concepts) of the target, and can have a `to` prop corresponding to the target location if different from the app location.
88+
By default, `<ContainerLayout>` renders one menu item per resource in the admin. To reorder the menu, omit resources, or add custom pages, pass a custom menu element to the `menu` prop.
89+
This element should be [a `<HorizontalMenu>` component](#horizontalmenu) with `<HorizontalMenu.DashboardItem>` or `<HorizontalMenu.Item>` children.
90+
Each child should have a `value` corresponding to the [application location](https://react-admin-ee.marmelab.com/documentation/ra-navigation#concepts) of the target, and can have a `to` prop corresponding to the target location if different from the app location.
8991

9092
```jsx
9193
import {
@@ -104,10 +106,14 @@ import {
104106

105107
const Menu = () => (
106108
<HorizontalMenu>
107-
<HorizontalMenu.Item label="Dashboard" to="/" value="" />
109+
<HorizontalMenu.DashboardItem label="Dashboard" value="" />
108110
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
109111
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
110112
<HorizontalMenu.Item label="Custom" to="/custom" value="custom" />
113+
<HorizontalMenu.Item label="Business" value="business">
114+
<HorizontalMenu.Item label="Sales" value="sales" >
115+
<HorizontalMenu.Item label="Customers" value="customers" >
116+
</HorizontalMenu.Item>
111117
</HorizontalMenu>
112118
);
113119

@@ -225,7 +231,6 @@ export const MyLayout = ({ children }) => (
225231
```
226232
{% endraw %}
227233

228-
## `<HorizontalMenu>`
229234

230235
This component renders a horizontal menu, to be used in the AppBar of the [`<ContainerLayout>`](#containerLayout).
231236

‎docs/HorizontalMenu.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
layout: default
3+
title: "HorizontalMenu"
4+
---
5+
6+
# `<HorizontalMenu>`
7+
8+
This [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" /> renders a horizontal menu component, alternative to react-admin's `<Menu>`, to be used in the AppBar of the [`<ContainerLayout>`](./ContainerLayout.md).
9+
10+
![Container layout](./img/container-layout.png)
11+
12+
`<HorizontalMenu>` is part of the [ra-navigation](https://react-admin-ee.marmelab.com/documentation/ra-navigation#containerlayout) package.
13+
14+
## Usage
15+
16+
Create a menu component based on `<HorizontalMenu>` and `<HorizontalMenu.Item>` (or `<HorizontalMenu.DashboardItem>`) children.
17+
18+
Each child should have a `value` corresponding to the [application location](https://react-admin-ee.marmelab.com/documentation/ra-navigation#concepts) of the target, and can have a `to` prop corresponding to the target location if different from the app location.
19+
20+
```jsx
21+
import { HorizontalMenu } from '@react-admin/ra-navigation';
22+
23+
export const Menu = () => (
24+
<HorizontalMenu>
25+
<HorizontalMenu.DashboardItem label="Dashboard" value="" />
26+
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
27+
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
28+
<HorizontalMenu.Item label="Business" value="business">
29+
<HorizontalMenu.Item label="Producers" to="/producers" value="producers" />
30+
<HorizontalMenu.Item label="Label" to="/label" value="label" />
31+
</HorizontalMenu.Item>
32+
<HorizontalMenu.Item label="Custom" to="/custom" value="custom" />
33+
</HorizontalMenu>
34+
);
35+
```
36+
37+
Then pass it to ta custom layout based on `<ContainerLayout>`, and make it the `<Admin layout>`:
38+
39+
```jsx
40+
import { Admin, Resource } from 'react-admin';
41+
import { ContainerLayout } from '@react-admin/ra-navigation';
42+
43+
import { Menu } from './Menu';
44+
45+
const MyLayout = ({ children }) => (
46+
<ContainerLayout menu={<Menu />}>
47+
{children}
48+
</ContainerLayout>
49+
);
50+
51+
const App = () => (
52+
<Admin dataProvider={dataProvider} layout={MyLayout}>
53+
...
54+
</Admin>
55+
);
56+
```
57+
58+
## Props
59+
60+
`<HorizontalMenu>` accepts the following props:
61+
62+
| Prop | Required | Type | Default | Description |
63+
| -------------- | -------- | --------- | ----------- | ---------------------------------------------------------------------------------------- |
64+
| `children` | Optional | | | The menu items to display. |
65+
| `hasDashboard` | Optional | Boolean | | Display an `<HorizontalMenu.DashboardItem>` with your resources if no children specified |
66+
67+
It also accept the props of [MUI Tabs](https://mui.com/material-ui/api/tabs/#props).
68+
69+
## `children`
70+
71+
When you use `<HorizontalMenu>` without any child, it automatically adds one menu item per resource.
72+
73+
If you want to customize the menu items, pass them as children to the `<HorizontalMenu>`. Each child should be a [`<HorizontalMenu.Item>`](#horizontalmenuitem) or a [`<HorizontalMenu.DashboardItem>`](#horizontalmenudashboarditem).
74+
75+
```jsx
76+
import { HorizontalMenu } from '@react-admin/ra-navigation';
77+
78+
export const Menu = () => (
79+
<HorizontalMenu>
80+
<HorizontalMenu.DashboardItem label="Dashboard" value="" />
81+
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
82+
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
83+
<HorizontalMenu.Item label="Business" value="business">
84+
<HorizontalMenu.Item label="Producers" to="/producers" value="producers" />
85+
<HorizontalMenu.Item label="Label" to="/label" value="label" />
86+
</HorizontalMenu.Item>
87+
<HorizontalMenu.Item label="Custom" to="/custom" value="custom" />
88+
</HorizontalMenu>
89+
);
90+
```
91+
92+
## `hasDashboard`
93+
94+
This prop lets you add a dashboard item when using `<HorizontalMenu>` with no children.
95+
96+
```tsx
97+
import { ContainerLayout, HorizontalMenu } from '@react-admin/ra-navigation';
98+
99+
const MyLayout = ({ children }) => (
100+
<ContainerLayout menu={<HorizontalMenu hasDashboard />}>
101+
{children}
102+
</ContainerLayout>
103+
);
104+
```
105+
106+
## `<HorizontalMenu.Item>`
107+
108+
An item for the `<HorizontalMenu>` component. Used to define access to a list view for a resource, or a custom route.
109+
110+
```tsx
111+
<HorizontalMenu>
112+
<HorizontalMenu.DashboardItem label="Home" />
113+
<HorizontalMenu.Item label="Artists" to="/artists" value="artists" />
114+
<HorizontalMenu.Item label="Songs" to="/songs" value="songs" />
115+
<HorizontalMenu.Item label="Labels" to="/labels" value="labels" />
116+
</HorizontalMenu>
117+
```
118+
119+
### Props
120+
121+
| Prop | Required | Type | Default | Description |
122+
| --------------- | -------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
123+
| `value` | Required | string | | The value of the Tab and the default route to use if no `to` is provided |
124+
| `label` | Optional | string | | The text to display |
125+
| `to` | Optional | string | | The route to which the item redirects |
126+
| `TabProps` | Optional | [TabProps](https://mui.com/material-ui/api/tabs/#props) | | Additional props of the Tab |
127+
| `MenuProps` | Optional | [MenuProps](https://mui.com/material-ui/api/menu/#props) | | Additional props of the Menu (`HorizontalMenu.Item` with children) |
128+
| `MenuItemProps` | Optional | [MenuItemProps](https://mui.com/material-ui/api/menu-item/#props) | | Additional props of the MenuItem (children of a `HorizontalMenu.Item`) |
129+
130+
### `label`
131+
132+
You can customize the label by setting the `label` prop. It is inferred from the `value` prop by default.
133+
134+
`<HorizontalMenu.Item>` uses the i18n layer, so you can translate the label. Check [the Translation chapter](./TranslationTranslating.md) for more information.
135+
136+
```tsx
137+
<HorizontalMenu>
138+
<HorizontalMenu.Item label="Artists" value="artists" />
139+
<HorizontalMenu.Item label="ra.custom.path.resource.song" value="songs" />
140+
</HorizontalMenu>
141+
```
142+
143+
### `MenuProps`
144+
145+
Additional props passed to the [Menu](https://mui.com/material-ui/api/menu/#props) (item displayed if it has children).
146+
147+
{% raw %}
148+
149+
```tsx
150+
<HorizontalMenu>
151+
<HorizontalMenu.Item
152+
value="songs"
153+
MenuProps={{ open: true, autoFocus: true }}
154+
>
155+
<HorizontalMenu.Item value="albums" />
156+
<HorizontalMenu.Item value="singles" />
157+
</HorizontalMenu.Item>
158+
</HorizontalMenu>
159+
```
160+
161+
{% endraw %}
162+
163+
### `MenuItemProps`
164+
165+
Additional props passed to the [MenuItem](https://mui.com/material-ui/api/menu-item/#props) (item displayed in a sub-menu).
166+
167+
{% raw %}
168+
169+
```tsx
170+
<HorizontalMenu>
171+
<HorizontalMenu.Item value="songs">
172+
<HorizontalMenu.Item
173+
value="albums"
174+
MenuItemProps={{
175+
divider: true,
176+
selected: isSelected(),
177+
}}
178+
/>
179+
<HorizontalMenu.Item value="singles" />
180+
</HorizontalMenu.Item>
181+
</HorizontalMenu>
182+
```
183+
184+
{% endraw %}
185+
186+
### `TabProps`
187+
188+
Additional props passed to the [Tab](https://mui.com/material-ui/api/tabs/#props).
189+
190+
{% raw %}
191+
192+
```tsx
193+
import { HorizontalMenu } from '@react-admin/ra-navigation';
194+
import MusicNoteIcon from '@mui/icons-material/MusicNote';
195+
196+
const Menu = () => (
197+
<HorizontalMenu>
198+
<HorizontalMenu.Item
199+
value="songs"
200+
TabProps={{ icon: <MusicNoteIcon />, iconPosition: 'start' }}
201+
/>
202+
</HorizontalMenu>
203+
);
204+
```
205+
206+
{% endraw %}
207+
208+
### `to`
209+
210+
You can customize the link of your resource by setting the `to` prop. It is inferred from the `value` prop by default as ``/${value}``.
211+
212+
```tsx
213+
<HorizontalMenu>
214+
<HorizontalMenu.Item to="/artists" value="artists" />
215+
<HorizontalMenu.Item to="/musics" value="songs" />
216+
</HorizontalMenu>
217+
```
218+
219+
### `value`
220+
221+
The `value` passed to the [MUI `Tab`](https://mui.com/material-ui/react-tabs/):
222+
223+
```tsx
224+
<HorizontalMenu>
225+
<HorizontalMenu.Item value="artists" />
226+
<HorizontalMenu.Item value="songs" />
227+
</HorizontalMenu>
228+
```
229+
230+
## `<HorizontalMenu.DashboardItem>`
231+
232+
This component adds a menu item that redirects to the `/` route. It accepts the same props as [`<HorizontalMenu.Item>`](#horizontalmenuitem).
233+
234+
```tsx
235+
<HorizontalMenu.DashboardItem value="" />
236+
```
237+
238+
## Adding Sub-Menus
239+
240+
<video controls autoplay playsinline muted loop>
241+
<source src="https://react-admin-ee.marmelab.com/assets/horizontal-menu-submenu.mp4" type="video/mp4"/>
242+
Your browser does not support the video tag.
243+
</video>
244+
245+
`<HorizontalMenu.Item>` creates a menu item for a given path. But you can also add `<HorizontalMenu.Item>` components as a child to create a submenu.
246+
247+
```jsx
248+
<HorizontalMenu>
249+
<HorizontalMenu.DashboardItem label="Home" />
250+
<HorizontalMenu.Item label="artists" to="/artists" value="artists" />
251+
<HorizontalMenu.Item label="Business" value="business">
252+
<HorizontalMenu.Item label="Producers" to="/producers" value="producers" />
253+
<HorizontalMenu.Item label="Label" to="/label" value="label" />
254+
</HorizontalMenu.Item>
255+
<HorizontalMenu.Item label="songs" to="/songs" value="songs" />
256+
</HorizontalMenu>
257+
```

‎docs/Reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ title: "Index"
9595

9696
**- H -**
9797

98-
* [`<HorizontalMenu>`](./ContainerLayout.md#horizontalmenu)<img class="icon" src="./img/premium.svg" />
98+
* [`<HorizontalMenu>`](./HorizontalMenu.md)<img class="icon" src="./img/premium.svg" />
9999

100100
**- I -**
101101

‎docs/img/container-layout.png‎

83.6 KB
Loading

‎docs/navigation.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@
253253
<ul><div>Other UI components</div>
254254
<li {% if page.path == 'Layout.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./Layout.html"><code>&lt;Layout&gt;</code></a></li>
255255
<li {% if page.path == 'ContainerLayout.md' %} class="active" {% endif %}><a class="nav-link" href="./ContainerLayout.html"><code>&lt;ContainerLayout&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
256+
<li {% if page.path == 'HorizontalMenu.md' %} class="active" {% endif %}><a class="nav-link" href="./HorizontalMenu.html"><code>&lt;HorizontalMenu&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
256257
<li {% if page.path == 'SolarLayout.md' %} class="active" {% endif %}><a class="nav-link" href="./SolarLayout.html"><code>&lt;SolarLayout&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
257258
<li {% if page.path == 'AppBar.md' %} class="active" {% endif %}><a class="nav-link" href="./AppBar.html"><code>&lt;AppBar&gt;</code></a></li>
258259
<li {% if page.path == 'Menu.md' %} class="active beginner" {% else %} class="beginner" {% endif %}><a class="nav-link" href="./Menu.html"><code>&lt;Menu&gt;</code></a></li>

‎docs/useDefineAppLocation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,4 +187,4 @@ The following components read the app location context:
187187
- [`<Breadcrumb>`](./Breadcrumb.md)
188188
- [`<MultiLevelMenu>`](./MultiLevelMenu.md)
189189
- [`<IconMenu>`](./IconMenu.md)
190-
- [`<HorizontalMenu>`](./ContainerLayout.md#horizontalmenu)
190+
- [`<HorizontalMenu>`](./HorizontalMenu.md)

0 commit comments

Comments
 (0)