Skip to content

Commit 236992b

Browse files
slax57slax57
authored
Merge pull request #8547 from marmelab/doc-cross-reference-containerlayout
[Doc] Fix `<ContainerLayout>` is hard to find.
2 parents 9884b68 + 6a48e82 commit 236992b

File tree

3 files changed

+120
-37
lines changed

3 files changed

+120
-37
lines changed

‎docs/Admin.md

+26-16
Original file line numberDiff line numberDiff line change
@@ -387,39 +387,49 @@ For more details on predefined themes and custom themes, refer to [the Theming c
387387

388388
If you want to deeply customize the app header, the menu, or the notifications, the best way is to provide a custom layout component. It must contain a `{children}` placeholder, where react-admin will render the resources.
389389

390-
Use the [default layout](https://github.com/marmelab/react-admin/blob/master/packages/ra-ui-materialui/src/layout/Layout.tsx) as a starting point, and check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples.
390+
React-admin offers predefined layouts for you to use:
391+
392+
- [`<Layout>`](./Layout.md): The default layout. It renders a top app bar and the navigation menu in a side bar.
393+
- [`<ContainerLayout>`](./ContainerLayout.md): A centered layout with horizontal navigation.
391394

392395
```jsx
393-
// in src/App.js
394-
import MyLayout from './MyLayout';
396+
import { Admin } from 'react-admin';
397+
import { ContainerLayout } from '@react-admin/ra-navigation';
395398

396-
const App = () => (
397-
<Admin layout={MyLayout} dataProvider={simpleRestProvider('http://path.to.my.api')}>
399+
export const App = () => (
400+
<Admin dataProvider={dataProvider} layout={ContainerLayout}>
398401
// ...
399402
</Admin>
400403
);
401404
```
402405

403-
Your custom layout can simply extend [the default `<Layout>` component](./Layout.md) if you only want to override the appBar, the menu, or the error page. For instance:
406+
These layouts can be customized by passing props to them. For instance, you can pass a custom `appBar` prop to `<Layout>` to override the default app bar:
404407

405408
```jsx
406409
// in src/MyLayout.js
407410
import { Layout } from 'react-admin';
408411
import MyAppBar from './MyAppBar';
409-
import MyMenu from './MyMenu';
410-
import MyError from './MyError';
411412

412-
const MyLayout = (props) => <Layout
413-
{...props}
414-
appBar={MyAppBar}
415-
menu={MyMenu}
416-
error={MyError}
417-
/>;
413+
export const MyLayout = (props) => <Layout {...props} appBar={MyAppBar} />;
414+
```
415+
416+
Then, pass it to the `<Admin>` component as the `layout` prop:
418417

419-
export default MyLayout;
418+
```jsx
419+
// in src/App.js
420+
import { Admin } from 'react-admin';
421+
import { MyLayout } from './MyLayout';
422+
423+
const App = () => (
424+
<Admin dataProvider={dataProvider} layout={MyLayout}>
425+
// ...
426+
</Admin>
427+
);
420428
```
421429

422-
For more details on custom layouts, check [the Theming documentation](./Theming.md#using-a-custom-layout).
430+
Refer to each component documentation to understand the props it accepts.
431+
432+
Finally, you can also pass a custom component as the `layout` prop. It must contain a `{children}` placeholder, where react-admin will render the content. Use the [default `<Layout>`](https://github.com/marmelab/react-admin/blob/master/packages/ra-ui-materialui/src/layout/Layout.tsx) as a starting point, and check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples.
423433

424434
## `loginPage`
425435

‎docs/ContainerLayout.md

+86-21
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,46 @@ See more details in the [ra-navigation documentation](https://marmelab.com/ra-en
2929

3030
## Props
3131

32-
`<ContainerLayout>` accepts the following props:
32+
`<ContainerLayout>` accepts the following props, all optional:
3333

34-
- `menu`: The menu component to use. Defaults to `<HorizontalMenu>`.
3534
- `appBar`: The component to use to render the top AppBar. Defaults to `<Header>`
36-
- `toolbar`: The buttons to render on the top right of the toolbar.
37-
- `maxWidth`: The maximum width of the content `<Container>`. Defaults to `md`.
3835
- `fixed`: Whether the content `<Container>` should be fixed. Defaults to false.
36+
- `maxWidth`: The maximum width of the content `<Container>`. Defaults to `md`.
37+
- `menu`: The menu component to use. Defaults to `<HorizontalMenu>`.
38+
- `sx`: The style of the layout, and the underlying component.
39+
- `toolbar`: The buttons to render on the top right of the toolbar.
40+
- `userMenu`: The component to use to render the user menu. Defaults to `<UserMenu>`.
41+
42+
## `appBar`
43+
44+
If you want to use a different color for the AppBar, or to make it sticky, pass a custom `appBar` element based on `<Header>`, which is a simple wrapper around [MUI's `<AppBar>` component](https://mui.com/material-ui/react-app-bar/#main-content).
45+
46+
```jsx
47+
import { ContainerLayout, Header } from '@react-admin/ra-navigation';
48+
49+
const myAppBar = <Header color="primary" position="sticky" />;
50+
const MyLayout = props => <ContainerLayout {...props} appBar={myAppBar} />;
51+
```
52+
53+
## `fixed`
54+
55+
If you prefer to design for a fixed set of sizes instead of trying to accommodate a fully fluid viewport, you can set the `fixed` prop. The max-width matches the min-width of the current breakpoint.
56+
57+
```jsx
58+
import { ContainerLayout } from '@react-admin/ra-navigation';
59+
60+
const MyLayout = props => <ContainerLayout {...props} fixed />;
61+
```
62+
63+
## `maxWidth`
64+
65+
This prop allows to set the maximum width of the content [`<Container>`](https://mui.com/material-ui/react-container/#main-content). It accepts a string, one of `xs`, `sm`, `md`, `lg`, `xl`, or `false` to remove side margins and occupy the full width of the screen.
66+
67+
```jsx
68+
import { ContainerLayout } from '@react-admin/ra-navigation';
69+
70+
const MyLayout = props => <ContainerLayout {...props} maxWidth="md" />;
71+
```
3972

4073
## `menu`
4174

@@ -86,16 +119,24 @@ export const App = () => (
86119
);
87120
```
88121

89-
## `appBar`
122+
## `sx`
90123

91-
If you want to use a different color for the AppBar, or to make it sticky, pass a custom `appBar` element based on `<Header>`, which is a simple wrapper around [MUI's `<AppBar>` component](https://mui.com/material-ui/react-app-bar/#main-content).
124+
The `sx` prop allows to customize the style of the layout, and the underlying component. It accepts a [MUI `sx` prop](https://mui.com/system/the-sx-prop/#main-content).
92125

126+
{% raw %}
93127
```jsx
94-
import { ContainerLayout, Header } from '@react-admin/ra-navigation';
128+
import { ContainerLayout } from '@react-admin/ra-navigation';
95129

96-
const myAppBar = <Header color="primary" position="sticky" />;
97-
const MyLayout = props => <ContainerLayout {...props} appBar={myAppBar} />;
130+
const MyLayout = props => (
131+
<ContainerLayout
132+
{...props}
133+
sx={{
134+
'& .MuiToolbar-root': { padding: 0 },
135+
}}
136+
/>
137+
);
98138
```
139+
{% endraw %}
99140

100141
## `toolbar`
101142

@@ -114,22 +155,46 @@ const toolbar = (
114155
const MyLayout = props => <ContainerLayout {...props} toolbar={toolbar} />;
115156
```
116157

117-
## `maxWidth`
158+
## `userMenu`
118159

119-
This prop allows to set the maximum width of the content [`<Container>`](https://mui.com/material-ui/react-container/#main-content). It accepts a string, one of `xs`, `sm`, `md`, `lg`, `xl`, or `false` to remove side margins and occupy the full width of the screen.
160+
By default, the `<ContainerLayout>` shows a user menu with a single item (logout) when the application has an `authProvider`. You can customize the user menu by passing a custom element to the `userMenu` prop.
120161

162+
{% raw %}
121163
```jsx
164+
import { Logout, UserMenu, useUserMenu } from 'react-admin';
165+
import { MenuList, MenuItem, ListItemIcon, ListItemText } from '@mui/material';
166+
import SettingsIcon from '@mui/icons-material/Settings';
122167
import { ContainerLayout } from '@react-admin/ra-navigation';
123168

124-
const MyLayout = props => <ContainerLayout {...props} maxWidth="md" />;
125-
```
126-
127-
## `fixed`
128-
129-
If you prefer to design for a fixed set of sizes instead of trying to accommodate a fully fluid viewport, you can set the `fixed` prop. The max-width matches the min-width of the current breakpoint.
130-
131-
```jsx
132-
import { ContainerLayout } from '@react-admin/ra-navigation';
169+
const ConfigurationMenu = React.forwardRef((props, ref) => {
170+
const { onClose } = useUserMenu();
171+
return (
172+
<MenuItem
173+
ref={ref}
174+
{...props}
175+
to="/configuration"
176+
onClick={onClose}
177+
sx={{ color: 'text.secondary' }}
178+
>
179+
<ListItemIcon>
180+
<SettingsIcon />
181+
</ListItemIcon>
182+
<ListItemText>Configuration</ListItemText>
183+
</MenuItem>
184+
);
185+
});
186+
187+
const CustomUserMenu = () => (
188+
<UserMenu>
189+
<MenuList>
190+
<ConfigurationMenu />
191+
<Logout />
192+
</MenuList>
193+
</UserMenu>
194+
);
133195

134-
const MyLayout = props => <ContainerLayout {...props} fixed />;
196+
export const MyLayout = props => (
197+
<ContainerLayout {...props} userMenu={<CustomUserMenu />} />
198+
);
135199
```
200+
{% endraw %}

‎docs/Layout.md

+8
Original file line numberDiff line numberDiff line change
@@ -320,3 +320,11 @@ export const MyLayout = (props) => (
320320
```
321321

322322
![React-Query DevTools](./img/react-query-devtools.png)
323+
324+
## Alternative Layouts
325+
326+
If you can't configure `<Layout>` to render the layout you want, you can use an alternative layout component, such as [`<ContainerLayout>`](./ContainerLayout.md): A centered layout with horizontal navigation.
327+
328+
![Container layout](https://marmelab.com/ra-enterprise/modules/assets/ra-navigation/latest/container-layout.png)
329+
330+
You can also write your own layout component from scratch. Check [the Theming documentation](./Theming.md#using-a-custom-layout) for examples

0 commit comments

Comments
 (0)