Admin: derivation rules and edge cases
Every rule that turns a Noun's properties, references and Verbs into the Admin's list, record page and forms, with the edge cases.
The Admin is the App a Startup's own team uses to read and change its records. It derives one list, one record page and two forms for each Noun, by the rules below.
The rules read only the definition: each property, each reference and each Verb. The same definition always derives the same screens. Whether a Startup needs screens at all is the choice in API only or with an App.
One list, one record page and two forms per Noun
The list shows at most 7 columns, in the order the properties are declared, with references last. It skips text, json and list properties, which need more room than a cell holds. One search box sits above every list.
The record page shows every property, and gives text and json the full width. A property past the seventh column, or one the list skips, appears there.
---
extends: [Thing]
properties:
residentName: string
residentEmail?: email
listingUrl?: url
startsOn: date
endsOn: date
monthlyRent: number
status: active | renewed | terminated
notes?: text
terms?: json
documents?: string[]
property: Property
verbs:
renew: {}
terminate: {}
---| Screen | What the Admin shows for Lease |
|---|---|
Lease list | Columns Resident Name, Resident Email, Listing Url, Starts On, Ends On, Monthly Rent and Status. One search box. Renew and Terminate on each row. |
Lease record page | Titled by residentName, such as Maya Ortiz. Every property, with Notes and Terms full width. Renew, Terminate and Edit. |
Lease create and edit forms | Resident Name, Resident Email, Listing Url and Status as one-line text boxes, Starts On and Ends On as date pickers, Monthly Rent as a number box, Notes as a multi-line box, Property as a picker. Terms and Documents have no input. The edit form adds Renew, Terminate and Delete. |
How a property becomes a control
The declared type decides the control in the forms, and how the list and the record page show the value.
5 more control rules wait for code that serves them.
A json property has no input, so the forms never change it. A list property, such as documents: string[], is left out of every form and every list, and shows on the record page only.
How a record names itself
Every record has one name, its representation. It titles the record page, fills a reference cell and labels each choice in a picker.
A Lease has none of the five names, so its first one-line property, residentName, names it. A title declared as text is skipped, because a multi-line value cannot name a record.
References
A property typed with another Noun, such as property: Property, is a reference. It shows the referenced record's name and links to that record. In the forms it takes a picker that searches the referenced records.
| Rule | When the definition has | The Admin shows |
|---|---|---|
reference-forward | a property typed with a Noun | its name in the list and on the record page; a picker in the forms |
A reference counts as the last column of the list. Lease has 7 short properties before property, so the list leaves property out and the record page shows it.
A Noun may point at itself. With manager: Employee on an Employee, the forms offer a picker over Employee records.
Actions and refusals
Each Verb a Noun declares beyond create, get, list, update and delete becomes a button. It sits on the record page, on the edit form and on each list row, labeled from its name: markWon reads Mark won.
A button runs its Verb on the record it sits on, and passes the record alone. It suits a Verb declared with {}, such as renew. A Verb declared with inputs gets a button but no form for those inputs.
Every button runs its Verb, and the Verb's rules decide. A refused Lease.renew leaves the record page as it was and shows why.
Portal screens for Software: members, seats and plan
The Portal screens Software adds over an API product's Portal, and the data states each screen handles: members, seats, workspaces and per-seat Offers.
Admin actions: Verbs, refusals and Approvals
How the Admin turns a Noun's custom Verbs into buttons, what a button runs, how a refusal shows, and where blocked Verbs and Approvals stand.