`useDefineAppLocation`

This Enterprise Edition hook lets you define the app location for a page, used by components like <Breadcrumb> and <IconMenu> to render the current location.

Usage

This component requires that the application layout is wrapped with <AppLocationContext> (which is already the case for <ContainerLayout> and <SolarLayout>):

// in src/MyLayout.jsx
import { AppLocationContext, Breadcrumb } from '@react-admin/ra-navigation';
import { Layout } from 'react-admin';

import { MyBreadcrumb } from './MyBreadcrumb';

export const MyLayout = ({ children, ...rest }) => (
    <AppLocationContext>
        <Layout {...rest}>
            <MyBreadcrumb />
            {children}
        </Layout>
    </AppLocationContext>
);

Then, a page component can define its app location by passing a string composed of location segments separated by a dot to the useDefineAppLocation hook:

// in src/UserPreferences.jsx
import { useDefineAppLocation } from '@react-admin/ra-navigation';

const UserPreferences = () => {
    useDefineAppLocation('user.preferences');
    return <span>My Preferences</span>;
};

Let’s say that this custom page is added to the app under the /preferences URL:

// in src/App.jsx
import { Admin, Resource, CustomRoutes, } from 'react-admin';
import { Route } from 'react-router-dom';

import { MyLayout } from './MyLayout';
import { UserPreferences } from './UserPreferences';

const App = () => (
    <Admin dataProvider={dataProvider} layout={MyLayout}>
        ...
        <CustomRoutes>
            <Route exact path="/preferences" component={UserPreferences} />,
        </CustomRoutes>
    </Admin>
);

Components inside the app, like <Breadcrumb>, can read the current app location and define custom items for the 'user.preferences' location.

// in src/MyBreadcrumb.jsx
import { Breadcrumb } from '@react-admin/ra-navigation';

export const MyBreadcrumb = () => (
    <Breadcrumb>
        <Breadcrumb.ResourceItems />
        <Breadcrumb.Item name="user" label="User">
            <Breadcrumb.Item name="preferences" label="Preferences" to="/preferences" />
        </Breadcrumb.Item>
    </Breadcrumb>
);

App Location For CRUD Pages

You don’t need to define the app location for CRUD pages as react-admin does it by default:

List: [resource].list
Create: [resource].create
Edit: [resource].edit. The location also contains the current record
Show: [resource].show. The location also contains the current record

However, you can customize these default app locations in your CRUD pages. For instance, to create a Post List page with the app location set to posts.published, you can do the following:

import { List, Datagrid, TextField } from 'react-admin';
import { useDefineAppLocation } from '@react-admin/ra-navigation';

export const PublishedPostsList = () => {
    useDefineAppLocation('posts.published');
    return (
        <List filter={{ isPublished: true }}>
            <Datagrid>
                <TextField source="title" />
                ...
            </Datagrid>
        </List>
    );
}

Dependent Components

The following components read the app location context: