ra-relationships

A set of alternative inputs and fields to edit relationships, including many-to-many relationships using a join table.

DualListInput

To let users choose mulitple values by moving them from a list of available choices to a list of selected choices, use a DualListInput. It renders using two Material ui's . Set the choices prop to determine the options (with id, name tuples):

const choices = [
   { id: 'programming', name: 'Programming' },
   { id: 'lifestyle', name: 'Lifestyle' },
   { id: 'photography', name: 'Photography' },
];
<DualListInput source="tags" choices={choices} />

Properties

You can also customize the properties to use for the option name and value, thanks to the 'optionText' and 'optionValue' attributes.

Usage

You can customize the properties to use for the option name and value, thanks to the optionText and optionValue attributes:

const choices = [
    { _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
    { _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
<DualListInput source="author_id" choices={choices} optionText="full_name" optionValue="_id" />

optionText also accepts a function, so you can shape the option text at will:

const choices = [
   { id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
   { id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const optionRenderer = choice => `${choice.first_name} ${choice.last_name}`;
<DualListInput source="author_id" choices={choices} optionText={optionRenderer} />

optionText also accepts a React Element, that will be cloned and receive the related choice as the record prop. You can use Field components there.

const choices = [
   { id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
   { id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const FullNameField = ({ record }) => <span>{record.first_name} {record.last_name}</span>;
<DualListInput source="gender" choices={choices} optionText={<FullNameField />}/>

The choices are translated by default, so you can use translation identifiers as choices:

const choices = [
   { id: 'M', name: 'myroot.gender.male' },
   { id: 'F', name: 'myroot.gender.female' },
];

However, in some cases, you may not want the choice to be translated. In that case, set the translateChoice prop to false.

<DualListInput source="gender" choices={choices} translateChoice={false}/>

Note that translateChoice is set to false when <DualListInput> is a child of <ReferenceInput>.

Tip: If you want to populate the choices attribute with a list of related records, you should decorate <DualListInput> with <ReferenceArrayInput>, and leave the choices empty:

import { ReferenceInput } from 'react-admin';
import { DualListInput } from '@react-admin/ra-relationships';

<ReferenceInput label="Author" source="author_id" reference="authors">
    <DualListInput optionText="last_name" />
</ReferenceInput>

You can set disabled values by setting the disabled property of one item:

const choices = [
    { _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
    { _id: 456, full_name: 'Jane Austen', sex: 'F' },
    { _id: 1, full_name: 'System Administrator', sex: 'F', disabled: true },
];
<DualListInput source="author_id" choices={choices} optionText="full_name" optionValue="_id" />

You can use a custom field name by setting disableValue prop:

const choices = [
    { _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
    { _id: 456, full_name: 'Jane Austen', sex: 'F' },
    { _id: 987, full_name: 'Jack Harden', sex: 'M', not_available: true },
];
<DualListInput source="contact_id" choices={choices} optionText="full_name" optionValue="_id" disableValue="not_available" />

Many-To-Many Relationships

Developers usually store many-to-many relationships in databases using an associative table (also known as join table, junction table or cross-reference table). For instance, if a Book can have many Authors, and an Author can write several Books, the normalized way to store this relationship in a relational database uses an intermediate table book_authors, as follows:

┌──────────────────┐       ┌──────────────┐      ┌───────────────┐
│ books            │       │ book_authors │      │ authors       │
│------------------│       │--------------│      │---------------│
│ id               │───┐   │ id           │      │ id            │
│ title            │   └──╼│ book_id      │   ┌──│ first_name    │
│ body             │       │ author_id    │╾──┘  │ last_name     │
│ publication_date │       │ is_public    │      │ date_of_birth │
└──────────────────┘       └──────────────┘      └───────────────┘

In the book_authors table, book_id and author_id are both foreign keys to books and authors.

A REST API closely following this data model exposes the three resources /books, /authors, and /book_authors. ra-many-to-many components rely on the associative table without ever showing it to the end user. From the end user's point of view, the associative table is an implementation detail.

Out of scope

If the associative table uses a composite primary key, then ra-many-to-many does not work, as react-admin require that all entities expose a identifier called id. For example, if user permissions is seen as a many-to-many relationship, it can be modeled in a relational database as follows:

users         user_permissions    permissions
----------    ----------------    -----------------                
login         user_login          key
password      permission_key      description
first_name
last_name

Here, the associative table uses a composite primary key made of the tuple (user_login, permission_key). To allow react-admin to use this associative table, the related API route (/user_permissions) must include a unique id field for each records (which can simply be the concatenation of the two foreign keys).

Also, if your REST API can present that relationship through a list of related record ids (e.g. author_ids in books and book_ids in authors), you don't need ra-many-to-many. Just use <ReferenceArrayField> and <ReferenceArrayInput>, which are standard components in react-admin.

<ReferenceManyToManyField>

This component fetches a list of referenced records by lookup in an associative table, and passes the records down to its child component, which must be an iterator component.

For instance, here is how to fetch the authors related to a book record by matching book.id to book_authors.post_id, then matching book_authors.author_id to authors.id, and then display the author last_name for each, in a <ChipField>:

import React from 'react';
import { 
    Show,
    SimpleShowLayout,
    TextField,
    DateField,
    SingleFieldList,
    ChipField,
} from 'react-admin';
import { ReferenceManyToManyField } from '@react-admin/ra-many-to-many';

export const BookShow = (props) => (
    <Show {...props}>
        <SimpleShowLayout>
            <TextField source="title" />
            <DateField source="publication_date">
            <ReferenceManyToManyField 
                reference="authors"
                through="book_authors"
                using="book_id,author_id"
            >
                <SingleFieldList>
                    <ChipField source="last_name" />
                </SingleFieldList>
            </ReferenceManyToManyField>
            <EditButton />
        </SimpleShowLayout>
    </Show>
);

<ReferenceManyToManyField> expects an iterator component as child, i.e. a component accepting a list of ids and a data object of the records indexed by id. That means you can use a <Datagrid> instead of a <SingleFieldList> - but not inside another <Datagrid>! This is useful if you want to display a more detailed view of related records. For instance, to display the author first_name and last_name:

export const BookShow = (props) => (
    <Show {...props}>
        <SimpleShowLayout>
            <TextField source="title" />
            <DateField source="publication_date">
            <ReferenceManyToManyField 
                reference="authors"
                through="book_authors"
                using="book_id,author_id"
            >
-               <SingleFieldList>
-                   <ChipField source="last_name" />
-               </SingleFieldList>
+               <Datagrid>
+                   <TextField source="first_name" />
+                   <TextField source="last_name" />
+               </Datagrid>
            </ReferenceManyToManyField>
            <EditButton />
        </SimpleShowLayout>
    </Show>
);

dataProvider Calls

<ReferenceManyToManyField> fetches the dataProvider twice in a row:

• once to get the records of the associative resource (book_authors in this case), using a getManyReference() call
• once to get the records of the reference resource (books in this case), using a getMany() call.

Note: You must add a <Resource> for the reference and associative resources - react-admin needs them to fetch the reference data. You can omit the list prop in this reference if you want to hide these resources in the sidebar menu.

For instance, if the user displays the book of id 123, <ReferenceManyToManyField> first issues the following query to the dataProvider:

dataProvider.getManyReference('book_authors', {
    target: 'book_id',
    id: 123,
});

Let's say that the dataProvider returns the following response:

{
    "data": [
        { "id": 667, "book_id": 123, "author_id": 732 },
        { "id": 895, "book_id": 123, "author_id": 874 },
    ],
    "total": 2,
}

Then, <ReferenceManyToManyField> issues a second query to the dataProvider:

dataProvider.getMany('books', {
    ids: [732, 874],
});

Props

Here are example usage for these props:

// You can specify the associative table name using the `through` prop.
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors_assoc"
>
   ...
</ReferenceManyToManyField>

// You can specify the associative table columns using the `using` prop.
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors"
    using="b_id,a_id"
>
   ...
</ReferenceManyToManyField>

// By default, react-admin restricts the possible values to 25
// and displays no pagination control. You can change the limit by setting the `perPage` prop:
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors"
    using="book_id,author_id"
    perPage={10}
>
   ...
</ReferenceManyToManyField>

// And if you want to allow users to paginate the list, pass a `<Pagination>` element as the `pagination` prop:
import { Pagination } from 'react-admin';
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors"
    using="book_id,author_id"
    pagination={<Pagination />}
>
   ...
</ReferenceManyToManyField>

// By default, react-admin orders the possible values by `id` desc.
// You can change this order by setting the `sort` prop (an object with `field` and `order` properties)
// to be applied to the associative resource.
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors"
    using="book_id,author_id"
    sort={{ field: 'id', order: 'DESC' }}
>
   ...
</ReferenceManyToManyField>

// Also, you can filter the records of the associative table using the `filter` prop.
<ReferenceManyToManyField 
    reference="authors"
    through="book_authors"
    using="book_id,author_id"
    filter={{ is_public: true }}
>
   ...
</ReferenceManyToManyField>

<ReferenceManyToManyInput>

This component allows to create, edit or remove relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider when the user submits the form, so that they can cancel the changes before submission.

To achieve this, you'll need to override the default save function provided by react-admin. That means the usage of RefereneManyInput requires a bit of extra code in the Form component, too.

Tip: As it creates or updates records of several resources, <ReferenceManyToManyInput> can only be used in a form where optimistic rendering is disabled (e.g <SimpleForm undoable={false}>).

For instance, here is how to edit the events related to an artists record through a performances associative table.

┌────────────┐       ┌──────────────┐      ┌────────┐
│ artists    │       │ performances │      │ events │
│------------│       │--------------│      │--------│
│ id         │───┐   │ id           │      │ id     │
│ first_name │   └──╼│ artist_id    │   ┌──│ name   │
│ last_name  │       │ event_id     │╾──┘  │        │
└────────────┘       └──────────────┘      └────────┘

In this example, artists.id matches performances.artist_id, and performances.event_id matches events.id. The form displays the events name in a <SelectArrayInput>:

import React, { FC, ComponentProps } from 'react';
import { Edit, SelectArrayInput, SimpleForm, TextInput } from 'react-admin';

import { ReferenceManyToManyInput, useReferenceManyToManyUpdate } from '@react-admin/ra-many-to-many';

type Props = ComponentProps<typeof Edit>;

/**
 * Decorate <SimpleForm> to override the default save function.
 * This is necessary to save changes in the associative table
 * only on submission.
 */
const ArtistEditForm: FC<Props> = props => {
    const save = useReferenceManyToManyUpdate({
        basePath: props.basePath,
        record: props.record,
        redirect: props.redirect || 'list',
        reference: 'events',
        resource: props.resource,
        source: 'id',
        through: 'performances',
        undoable: props.undoable,
        using: 'artist_id,event_id',
    });

    return <SimpleForm {...props} save={save} />;
};

const ArtistEdit: FC<Props> = props => (
    <Edit {...props}>
        <ArtistEditForm>
            <TextInput disabled source="id" />
            <TextInput source="first_name" />
            <TextInput source="last_name" />
            <ReferenceManyToManyInput
                source="id"
                reference="events"
                through="performances"
                using="artist_id,event_id"
                fullWidth
                label="Performances"
            >
                <SelectArrayInput optionText="name" />
            </ReferenceManyToManyInput>
        </ArtistEditForm>
    </Edit>
);

export default ArtistEdit;

import React, { FC, ComponentProps } from 'react';
import { Edit, SelectArrayInput, SimpleForm, TextInput } from 'react-admin';

import { ReferenceManyToManyInput, useReferenceManyToManyUpdate } from '@react-admin/ra-many-to-many';

type Props = ComponentProps<typeof Edit>;

/**
 * Decorate <SimpleForm> to override the default save function.
 * This is necessary to save changes in the associative table
 * only on submission.
 */
const ArtistEditForm: FC<Props> = props => {
    const save = useReferenceManyToManyUpdate({
        basePath: props.basePath,
        record: props.record,
        redirect: props.redirect || 'list',
        reference: 'events',
        resource: props.resource,
        source: 'id',
        through: 'performances',
        undoable: props.undoable,
        using: 'artist_id,event_id',
    });

    return <SimpleForm {...props} save={save} />;
};

const ArtistEdit: FC<Props> = props => (
    <Edit {...props}>
        <ArtistEditForm>
            <TextInput disabled source="id" />
            <TextInput source="first_name" />
            <TextInput source="last_name" />
            <ReferenceManyToManyInput
                source="id"
                reference="events"
                through="performances"
                using="artist_id,event_id"
                fullWidth
                label="Performances"
            >
                <SelectArrayInput optionText="name" />
            </ReferenceManyToManyInput>
        </ArtistEditForm>
    </Edit>
);

export default ArtistEdit;

dataProvider Calls

When rendered, <ReferenceManyToManyInput> fetches the dataProvider three times in a row:

• once to get the records of the associative resource (performances in this case), using a getManyReference() call
• once to get the records of the reference resource (events in this case), using a getMany() call.
• once to get the possible values of the reference resource (events in this case) to show as suggestions in the input, using a getList() call

Note: You must add a <Resource> for the reference and associative resources - react-admin needs them to fetch the reference data. You can omit the list prop in the associative recource if you want to hide it in the sidebar menu.

For instance, if the user edits the artist of id 123, <ReferenceManyToManyInput> first issues the following query to the dataProvider:

dataProvider.getManyReference('performances', {
    target: 'artist_id',
    id: 123,
});

Let's say that the dataProvider returns the following response:

{
    "data": [
        { "id": 667, "artist_id": 123, "event_id": 732 },
        { "id": 895, "artist_id": 123, "event_id": 874 },
    ],
    "total": 2,
}

Then, <ReferenceManyToManyInput> issues a second query to the dataProvider:

dataProvider.getMany('events', {
    ids: [732, 874],
});

Which returns the following:

{
    "data": [
        { "id": 732, "name": "Acme Rock Festival" },
        { "id": 874, "name": "Roll and Rock 2020" }
    ]
}

That's enough to display the current value in the input. But to display events suggestions, the component makes a final call:

dataProvider.getList('events', {
    sort: { field: 'id', order: 'DESC' },
    pagination: { page: 1, perPage: 25 },
    filter: {},
});

{
    "data": [
        { "id": 1, "name": "Rock Your Town" },
        { "id": 2, "name": "Aime le Rock" },
        { "id": 3, "name": "Breed Festival" },
        ...
    ]
}

And that's it for the display phase.

When the user submits the form, the save function returned by the useReferenceManyToManyUpdate hook compares the value of the ReferenceManyToManyInput (the list of relationships edited by the user) with the value previously returned by the dataProvider. Using a diffing algorithm, it deduces a list of insertions and deletions in the associative table, that are executed in a row.

For instance, let's say that after displaying the events 732 and 874 where artists 123 performs, the user removes event 732, and adds events 2 and 3. Upon submission, the dataProvider will detect removals and additions, and send the following queries:

dataProvider.delete('performances', { 
    id: 732,
    previousData: { id: 732, name: 'Acme Rock Festival' },
});
dataProvider.create('performances', { 
    data: { artist_id: 123, event_id: 2 }
});
dataProvider.create('performances', { 
    data: { artist_id: 123, event_id: 3 }
});

Props