Admin panel
Relations in the admin panel
The CMS reads a table’s relations from its descriptor and draws each one by what it is:
| Relation | In the record |
|---|---|
belongsTo |
a picker of the related row, in place of its foreign-key column |
hasOne |
a picker of the one related row |
hasMany, manyToMany, a to-many via |
a tab listing the related rows |
a via that is not writable |
read-only |
// backend/schema/articles.tsimport { defineTable, col, rel } from "@rebasepro/server/schema";import { users } from "./users";import { tags } from "./tags";
export const articles = defineTable("articles", { columns: { id: col.uuid().primaryKey().defaultRandom(), title: col.text().notNull(), }, relations: { author: rel.belongsTo(() => users, { notNull: true }), tags: rel.manyToMany(() => tags), featuredTags: rel.manyToMany(() => tags, { through: "articles_featured_tags" }), }, rls: "admin-only",});The form shows Author as a picker of a user and no authorId field: the
picker edits that column. It is required, because the foreign key is
NOT NULL with no default. A foreign key that is part of the table’s primary key
stays a field of its own beside the picker. Tags and Featured Tags are
tabs of the record.
A relation whose target the caller is not served is left out: the CMS cannot
open a table it does not have. A belongsTo then leaves its foreign key as a
plain field, so the value stays visible and editable. A belongsTo whose
foreign key the caller may not read is left out too.
The path segment is the relation name
Section titled “The path segment is the relation name”A tab’s rows are addressed as parent/parentId/relationName:
/c/authors/a-1/posts the posts of author a-1/c/articles/p-1/featuredTags the featured tags of article p-1The last segment is the relation’s name, the key in relations, not the
target’s slug. That is what lets two relations to the same table work: each has
its own name, so each gets its own tab and its own path.
Owned rows versus shared rows
Section titled “Owned rows versus shared rows”What a tab lets you do depends on how the relation is stored:
One-to-many (hasMany) |
Many-to-many (manyToMany) |
|
|---|---|---|
| The child belongs to | this parent alone | every parent that links it |
| Create | creates the row under this parent | creates the row and links it |
| Add existing | — | links an existing row |
| Remove | deletes the row | unlinks it; the row is untouched |
A many-to-many tab offers Add existing and Remove from this record, and never a delete that would take the row away from other parents.
The same rules over REST
Section titled “The same rules over REST”A tab is an ordinary query narrowed to one parent, so it accepts everything a
root list does (filters, orderBy, limit, offset, include) and
meta.total counts the filtered rows. Filter per field (?field=op.value) or
with a whole-object ?where={"field":["op","value"]}:
GET /api/data/authors/a-1/posts?status=eq.published&orderBy=title&limit=20GET /api/data/authors/a-1/posts?where={"status":["==","published"]}&orderBy=titleGET /api/data/authors/a-1/posts/p-1POST /api/data/authors/a-1/posts create under this parentPATCH /api/data/authors/a-1/posts/p-1 update; will not reparentDELETE /api/data/authors/a-1/posts/p-1 delete (one-to-many) / unlink (many-to-many)The parent segment is enforced. Addressing a row that is not under that parent
returns 404, and PATCH never moves a row from one parent to another: set the
foreign key explicitly if that is what you want.
For a many-to-many, PATCH parent/id/child/childId is set membership: it links
the row if it is not linked yet, and is idempotent. That is how you attach a row
that already exists.
What does not become a tab
Section titled “What does not become a tab”- To-one relations: a
belongsToor ahasOneis a field of the record, not a list. Writing through a to-one path is rejected. - A table with
hideFromEntityViewsin itscustomizeTableis not offered as a tab on the records of tables that relate to it.
Customizing relation fields
Section titled “Customizing relation fields”// frontend/src/cms/articles.tsximport { customizeTable } from "@rebasepro/cms";import type { articles } from "../../../backend/schema/articles";
export const articlesCms = customizeTable<typeof articles>("articles", { fields: { author: { previewFields: ["displayName", "email"], widget: "dialog", includeEntityLink: true, }, featuredTags: { name: "Featured", renderInForm: true, overrides: { name: "Featured tags", defaultViewMode: "cards" }, }, },});| Option | Effect |
|---|---|
previewFields |
The target’s fields shown in the chip for a related row. At most three fit. |
widget |
"select" picks from a dropdown, "dialog" from a searchable table. |
fixedFilter |
Offer only rows that pass this filter. |
includeId |
Show the related row’s id in previews. |
includeEntityLink |
Show a link that opens the related row. |
renderInForm |
Also draw a to-many relation as a picker in the form, beside its tab. |
overrides |
How the target is presented in this relation’s tab: any table option except fields. |
overrides restyles the tab, not the target’s fields. Those belong to the
target table’s own customizeTable, and writing fields inside overrides
throws.
Next steps
Section titled “Next steps”- Relations: the five kinds, and how to declare each
- customizeTable: relation options in the reference
- Writing over REST: create, update and delete beyond a tab