Skip to content

Commit b93c6a2

Browse files
fzaninottofzaninotto
authored
Merge pull request #9404 from marmelab/doc-custom-routes
[Doc] Add illustrations to the `<CustomRoutes>` chapter
2 parents f69c7e2 + da6eb0a commit b93c6a2

File tree

3 files changed

+86
-32
lines changed

3 files changed

+86
-32
lines changed

‎docs/CustomRoutes.md

+86-32
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ Alternatively, you can add your custom routes to resources. They will be availab
1717
import { Admin, Resource, CustomRoutes } from 'react-admin';
1818
import { Route } from "react-router-dom";
1919

20-
import dataProvider from './dataProvider';
20+
import { dataProvider } from './dataProvider';
2121
import posts from './posts';
2222
import comments from './comments';
23-
import Settings from './Settings';
24-
import Profile from './Profile';
23+
import { Settings } from './Settings';
24+
import { Profile } from './Profile';
2525

2626
const App = () => (
2727
<Admin dataProvider={dataProvider}>
@@ -39,18 +39,20 @@ export default App;
3939

4040
Now, when a user browses to `/settings` or `/profile`, the components you defined will appear in the main part of the screen.
4141

42+
**Tip**: Custom routes don't automatically appear in the menu. You have to manually [customize the menu](#adding-custom-routes-to-the-menu) if you want custom routes to be accessible from the menu.
43+
4244
## `children`
4345

44-
`children` of the `<CustomRoutes>` component must be `<Route>` elements from [react-router-dom](https://reactrouter.com/en/6/start/concepts#defining-routes), and map a path with a custom element.
46+
`children` of the `<CustomRoutes>` component must be `<Route>` elements from [react-router-dom](https://reactrouter.com/en/6/start/concepts#defining-routes), mapping a `path` with a custom `element`.
4547

4648
```jsx
4749
// in src/App.js
4850
import { Admin, Resource, CustomRoutes } from 'react-admin';
4951
import { Route } from "react-router-dom";
5052

51-
import dataProvider from './dataProvider';
52-
import Settings from './Settings';
53-
import Profile from './Profile';
53+
import { dataProvider } from './dataProvider';
54+
import { Settings } from './Settings';
55+
import { Profile } from './Profile';
5456

5557
const App = () => (
5658
<Admin dataProvider={dataProvider}>
@@ -64,19 +66,25 @@ const App = () => (
6466
export default App;
6567
```
6668

69+
You can learn more about the `<Route>` element in the [react-router-dom documentation](https://reactrouter.com/en/6/start/concepts#defining-routes).
70+
6771
## `noLayout`
6872

69-
By default, custom routes render within the application layout (with the menu and the app bar). If you want a custom route to render without the layout, e.g. for registration screens, then provide the `noLayout` prop on the `<CustomRoutes>` element:
73+
By default, custom routes render within the application layout. If you want a custom route to render without the layout, e.g. for registration screens, then provide the `noLayout` prop on the `<CustomRoutes>` element.
74+
75+
<img src="./img/custom-route-nolayout.png" class="no-shadow" alt="custom route with no layout" />
76+
77+
Here is an example of application configuration mixing custom routes with and without layout:
7078

7179
```jsx
7280
// in src/App.js
7381
import { Admin, CustomRoutes } from 'react-admin';
7482
import { Route } from "react-router-dom";
7583

76-
import dataProvider from './dataProvider';
77-
import Register from './Register';
78-
import Settings from './Settings';
79-
import Profile from './Profile';
84+
import { dataProvider } from './dataProvider';
85+
import { Register } from './Register';
86+
import { Settings } from './Settings';
87+
import { Profile } from './Profile';
8088

8189
const App = () => (
8290
<Admin dataProvider={dataProvider}>
@@ -93,9 +101,13 @@ const App = () => (
93101

94102
As illustrated above, there can be more than one `<CustomRoutes>` element inside an `<Admin>` component.
95103

96-
## Custom Page Title
104+
## Customizing The Page Title
97105

98-
To define the page title (displayed in the app bar), your custom pages can use [the `<Title>` component](./Title.md) from react-admin:
106+
To define the page title (displayed in the app bar), custom pages should use [the `<Title>` component](./Title.md).
107+
108+
<img src="./img/custom-route-title.png" class="no-shadow" alt="custom route title" />
109+
110+
Here is a simple example:
99111

100112
```jsx
101113
// in src/Settings.js
@@ -117,22 +129,11 @@ export default Settings;
117129

118130
`<Title>` uses a [React Portal](https://react.dev/reference/react-dom/createPortal), so it doesn't matter *where* you put it in your component. The title will always be rendered in the app bar.
119131

120-
## Linking To Custom Routes
132+
## Adding Custom Routes to the Menu
121133

122-
You can link to your pages using [react-router's Link component](https://reactrouter.com/en/main/components/link):
134+
To add your custom pages to the navigation menu, you have to replace the default menu by a [custom menu](./Menu.md) with entries for the custom pages.
123135

124-
```jsx
125-
import { Link as RouterLink } from 'react-router-dom';
126-
import { Link } from '@mui/material';
127-
128-
const SettingsButton = () => (
129-
<Link component={RouterLink} to="/settings">
130-
Settings
131-
</Link>
132-
);
133-
```
134-
135-
Alternately, create a [custom menu](./Menu.md) with entries for the custom pages.
136+
First, create a custom menu. Make sure to use the same value in the `<Menu.Item to>` prop as in the `<Route path>` prop.
136137

137138
```jsx
138139
// in src/MyMenu.js
@@ -143,23 +144,76 @@ import PeopleIcon from '@mui/icons-material/People';
143144
export const MyMenu = () => (
144145
<Menu>
145146
<Menu.DashboardItem />
146-
<Menu.ResourceItem name="posts" />
147-
<Menu.ResourceItem name="comments" />
147+
<Menu.ResourceItems />
148148
<Menu.Item to="/settings" primaryText="Users" leftIcon={<SettingsIcon />}/>
149149
<Menu.Item to="/profile" primaryText="Miscellaneous" leftIcon={<PeopleIcon />}/>
150150
</Menu>
151151
);
152152
```
153153

154+
Next, pass the custom menu to a custom `<Layout>` component:
155+
156+
```jsx
157+
// in src/MyLayout.js
158+
import { Layout } from 'react-admin';
159+
import { MyMenu } from './MyMenu';
160+
161+
export const MyLayout = (props) => <Layout {...props} menu={MyMenu} />;
162+
```
163+
164+
Finally, pass the custom `<Layout>` component to `<Admin>`:
165+
166+
```jsx
167+
// in src/App.js
168+
import { Admin, Resource, CustomRoutes } from 'react-admin';
169+
import { Route } from "react-router-dom";
170+
171+
import { dataProvider } from './dataProvider';
172+
import { MyLayout } from './MyLayout';
173+
import posts from './posts';
174+
import comments from './comments';
175+
import { Settings } from './Settings';
176+
import { Profile } from './Profile';
177+
178+
const App = () => (
179+
<Admin dataProvider={dataProvider} layout={MyLayout}>
180+
<Resource name="posts" {...posts} />
181+
<CustomRoutes>
182+
<Route path="/settings" element={<Settings />} />
183+
<Route path="/profile" element={<Profile />} />
184+
</CustomRoutes>
185+
</Admin>
186+
);
187+
```
188+
189+
To learn more about custom menus, check [the `<Menu>` documentation](./Menu.md).
190+
191+
## Linking To Custom Routes
192+
193+
You can link to your pages using [react-router's Link component](https://reactrouter.com/en/main/components/link). Make sure to use the same value in the `<Link to>` prop as in the `<Route path>` prop.
194+
195+
```jsx
196+
import { Link as RouterLink } from 'react-router-dom';
197+
import { Link } from '@mui/material';
198+
199+
const SettingsButton = () => (
200+
<Link component={RouterLink} to="/settings">
201+
Settings
202+
</Link>
203+
);
204+
```
205+
154206
## Sub-Routes
155207

156-
If you want to add sub-routes to a resource, add the `<Route>` elements as [children of the `<Resource>` element](./Resource.md#children):
208+
Sometimes you want to add more routes to a resource path. For instance, you may want to add a custom page to the `/posts` resource, such as `/posts/analytics`.
209+
210+
To do so, add the `<Route>` elements as [children of the `<Resource>` element](./Resource.md#children):
157211

158212
```jsx
159213
import { Admin, Resource } from 'react-admin';
160214
import { Route } from "react-router-dom";
161215

162-
import dataProvider from './dataProvider';
216+
import { dataProvider } from './dataProvider';
163217
import posts from './posts';
164218

165219
const App = () => (

‎docs/img/custom-route-nolayout.png

23.3 KB
Loading

‎docs/img/custom-route-title.png

20.2 KB
Loading

0 commit comments

Comments
 (0)