Last updated
Last updated
@adminjs/relations
is a feature which allows you to manage one-to-many
and many-to-many
relations within your admin panel.
As of version 1.0.0
it supports:
listing multiple one-to-many
relations with pagination but no filters in the details view of a record,
listing multiple many-to-many
relations with pagination but no filters in the details view of a record,
editing and creating one-to-many
relations,
editing many-to-many
relations,
deleting records listed in one-to-many
table (if you want to only remove the relation, you can just modify the target record)
deleting relations in junction table of many-to-many
relation or deleting the target record of a many-to-many
relation (it also deleted the relation in junction table)
navigating to details view of a target relation,
adding an existing record to a many-to-many
relation or creating a new record which will be assigned to your many-to-many
relation.
All premium features currently use One Time Payment model and you can use them in all apps that belong to you. Once you purchase the addon, you will receive a license key which you should provide in @adminjs/relations
configuration in your application's code.
Installing the library:
The license key should be provided to owningRelationSettingsFeature
:
targetRelationSettingsFeature
does not require a license key as it's role is mostly utility-only. The documentation below describes the configuration objects and setup instructions in more detail.
If you encounter any issues or require help installing the package please contact us at adminjs@adminjs.co or through our Discord server.
Similarly to other features, the @adminjs/relations
feature has to be imported into features
configuration section of your resource. @adminjs/relations
exports two separate feature that you must configure in order for the functionality to work:
owningRelationSettingsFeature
is used to configure the relations that you will want to manage later,
targetRelationSettingsFeature
doesn't require any configuration, but it has to be included in targetted resource in order for redirects and many-to-many
assignments to work properly.
The two features will be explained in more detail in the later parts of this guide.
The usage guide will be based on sample database tables which can be represented by the following interfaces:
@adminjs/relations
is adapter-agnostic which means you can use it regardless of the database adapter you had installed. Nevertheless, some ORMs automatically generate and manage junction tables for you without you having to actually create entities for them in your codebase. This will not work with AdminJS and you will have to create actual entities for junction tables and register them as AdminJS resources since AdminJS uses them to find your M:N
records.
AdminJS requires every resource to have a primary key column, this includes junction tables.
Below you can find feature options of owningRelationSettingsFeature
which you can use for reference.
If using Prisma, configure the joinKey
and inverseJoinKey
options by providing the relation names instead of foreign keys, for example: organization
instead of organizationId
According to the database structure described above as well as the presented configuration options of owningRelationSettingsFeature
, this is how you can add this feature to Organization
resource which can have many Persons
and Offices
Additionally, in your Office
and Person
resources you will have to add targetRelationSettingsFeature
:
If you configure your resources as shown above, you should be able to see Persons
and Offices
tabs in your Organization
record's details view.
The example below shows how you can configure a many-to-many
relation between Team
and Person
through TeamMember
.
Additionally, in your Person
resource you will have to make sure to add targetRelationSettingsFeature
. Of course, if you had added it before you don't have to add it multiple times.
By default all actions related to managing the relations will be available for everyone. You can modify the accessibility in the same way you modify accessibility of your custom actions.
@adminjs/relations
introduces the following new actions to your resource:
findRelation
is used to list one-to-many
and many-to-many
records from the target resource,
addManyToManyRelation
is used to add existing records to a junction table for many-to-many
relations
deleteRelation
is used to delete a record from a junction table, deleting the relation in the process, but leaving both records
Taking Team
resource from above as an example, you can allow these actions only for users with role Admin
by doing the following changes:
@adminjs/relations
is a premium feature which can be purchased at
You can read more about RBAC in AdminJS in .
@adminjs/relations