Field types
Fields are written as name:type, separated by commas:
nevela resource Product --fields="name:string, sku:string!, price:money, notes:text?"Suffixes
Section titled “Suffixes”| Suffix | Meaning | Example |
|---|---|---|
? |
Optional. The column is nullable. | notes:text? |
! |
Unique. No two records share a value. | sku:string! |
Both can be combined: code:string?!.
= after the type gives a default, used when a create leaves the field out: status:enum(pending|paid)=pending, quantity:int=1, active:boolean=true. A required boolean left out is false without being told, so it doesn’t need =false.
| Type | Stored as | Validation |
|---|---|---|
string |
string |
text, up to 255 characters |
text |
text |
text, up to 65,535 characters |
richtext |
longText |
formatted text, kept as cleaned HTML, up to 65,535 characters |
email |
string |
a valid email address, kept in small letters, so Ada@Example.COM and ada@example.com are one address |
url |
string (2,048) |
a valid http or https address |
tel |
string |
a real number of any country, kept as +256772123456 |
tel(UG) |
string |
a number of that country, kept as +256772123456 |
slug |
string |
letters, numbers, dashes and underscores |
slug(title) |
string |
the same, made from the title when left empty (post-title, then post-title-2) |
color |
string |
a hex colour, kept as #aabbcc, so #ABC and #aabbcc are one colour |
domain |
string (253) |
a bare host in small letters: https://Example.COM/about is kept as example.com, and münchen.de as xn--mnchen-3ya.de |
country |
string (2) |
a two-letter code such as UG, picked from a searchable list |
country(UG) |
string (2) |
the same, and UG when a create leaves it out |
time |
string (5) |
a time of day, kept as 09:05 |
json |
json |
an object or a list, edited as JSON, and not searched, sorted or filtered by. Give what has a known shape fields of its own |
int |
integer |
a whole number |
float |
double |
a number |
money |
decimal(12, 2) |
a number |
percent |
double |
a number from 0 to 100 |
rating |
integer |
a whole number from 1 to 5, as stars |
rating(10) |
integer |
the same, from 1 to the number you give, up to 10 |
boolean |
boolean |
true or false |
date |
date |
a date as YYYY-MM-DD |
datetime |
dateTime |
a date and time |
enum(a|b|c) |
string, indexed |
one of the listed values |
belongsTo(Resource) |
a foreign key, indexed | the id of a record that exists |
image |
string (the file’s key) |
a picture uploaded to this field |
file(pdf|image) |
string (the file’s key) |
a file of a listed kind, uploaded to this field |
file(pdf|private) |
string (the file’s key) |
the same, kept private |
files(image) |
json (the files’ keys) |
several files uploaded to this field, up to 20 |
The dashboard picks the input and the table column from the type.
Which columns the table shows
Section titled “Which columns the table shows”A table starts with its first six columns, and the date each record was created. The other columns are in the Columns menu above the table, to turn on. Long text, a string longer than 255 characters, and a file that isn’t a picture start off whatever their place, because a paragraph in a row makes the table too wide to read. A cell never grows past a set width: a value too long for it ends in “…”, and the whole of it shows when you point at it.
A field’s list in the descriptor decides for it:
list |
The column |
|---|---|
true |
Always on, even past the sixth or for long text. |
"hidden" |
In the Columns menu, and off until someone turns it on. |
false |
Not in the table at all. |
"notes": { "kind": "text", "required": false, "list": true }Run nevela generate after changing it. What someone turns on or off goes in the page’s address (?columns=name,email), so a link to it opens with the same columns.
Numbered by Laravel
Section titled “Numbered by Laravel”An order number, an invoice number or a ticket number is given by the app, one after another:
nevela resource Invoice --fields="number:auto(INV), customer:string, total:money"The first invoice is INV-0001, the next INV-0002, and on past INV-9999 to INV-10000. Grit’s way of writing it, number:string:auto:INV, means the same, and in the descriptor it is "auto": "INV" on a string field. The prefix is letters and digits, up to ten, starting with a letter.
- Left empty, it is given the next one when the record is made: in the form, over the API, by an import or by your own code (
Invoice::create([...])). The form says so in the field. One typed in is kept. - It is unique, and a number isn’t given again, not one in the trash and not one removed for good.
- Records made at the same moment each get their own. The last number given is kept in a table of Nevela’s,
nevela_numbers, and its row is locked while the next is worked out, so nothing is refused for having the same number as another. A number typed in counts too: type INV-5000, and the next one given is INV-5001. - A number can be skipped. A record that fails after it was given one doesn’t give it back, unless the failure undoes a transaction it was part of, as saving a record with its lines is.
- Seeding goes on from the last number given, however many times you run it: INV-0001 to INV-0020, then INV-0021.
nevela seed --freshstarts the numbers again.
Copied from a related record
Section titled “Copied from a related record”An order item’s price is its product’s. Rather than type it, copy it:
nevela resource OrderItem --fields="product:belongsTo(Product), quantity:int, price:money(product.price)"(product.price) is a relation of the resource and a field of the record it points at, of the same type. In the descriptor it is "from": "productId.price".
- The copy is made when the record is made, and again when it is pointed at another (the item is changed to another product). Otherwise it is kept: when a product’s price changes, the orders already made keep the price they were sold at.
- It isn’t typed. The form shows it and doesn’t ask for it, and in an order’s line items the price is in the row as soon as the product is picked. What a request sends for it is left out.
- It is copied however the record is saved: the dashboard, the API, an import, or your own code.
- A copy can’t be unique, or a file or a relation.
What an enum’s values are called
Section titled “What an enum’s values are called”A value is what is stored, validated and sent over the API, so it is a short key: asap, quarter. What people read can be words, given after =:
nevela resource ProjectRequest --fields="name:string, timeline:enum(asap=As soon as possible|month=Within a month|quarter=In 1 to 3 months|flexible)"or in the descriptor:
"timeline": { "kind": "enum", "options": ["asap", "month", "quarter", "flexible"], "optionLabels": { "asap": "As soon as possible", "month": "Within a month", "quarter": "In 1 to 3 months" }}The dashboard uses the words everywhere it shows the value: the table, its filters, the form, a record’s page, the stat cards and the charts. A value with no label is made readable from the key: flexible reads “Flexible”, on_hold “On hold”. A label for a value that isn’t one of options is refused when the descriptor is read.
Your own code can say the same words, for an email or a PDF, without keeping a copy of them:
$request->optionLabel('timeline'); // "In 1 to 3 months"Every generated model with an enum field has it. The descriptor has it too: Nevela::resource('ProjectRequest')->fields['timeline']->optionLabel('quarter').
Money and its currency
Section titled “Money and its currency”A money field is shown in a currency when one is set: for the whole app in apps/api/.env, or on the field.
NEVELA_CURRENCY=UGX"quoteAmount": { "kind": "float", "format": "money", "currency": "UGX" }A field’s own wins. It is written with the currency’s own decimals, so UGX 4,500,000 and $4,500,000.00, and the input shows the code beside the number. A currency with no decimals, such as UGX, takes whole numbers only. The code is ISO 4217’s, in capitals: anything else is refused. With neither set, money looks as it always has.
Run nevela generate after changing NEVELA_CURRENCY.
A field that only sometimes applies
Section titled “A field that only sometimes applies”A billing cycle belongs to a recurring project and means nothing on a one-off one. if after a field says which records it is for:
nevela resource Project --fields="name:string, kind:enum(one_off|recurring), cycle:enum(monthly|annually) if kind == recurring, amount:money"| Where it applies (a recurring project) | Everywhere else (a one-off) |
|---|---|
| The form shows it, marked required. | The form doesn’t show it. |
| Left empty, it is refused: “Needed when the kind is Recurring.” | It is empty. Sent anyway, it is not kept. |
A project changed from recurring to one-off loses its cycle, and one changed the other way needs one sent with the change. A change that sends neither keeps what the record has. Laravel holds to this however a record arrives (the form, the API, “Add several”, a CSV import, a public form), and the seeder gives a cycle only to the recurring projects it makes. The column is nullable, since most rows may have nothing in it.
| Several values | rate:money if kind == recurring|retainer |
| A yes/no field | terms:text if billed == true |
| Optional where it applies | discount:percent? if kind == recurring is never needed, but still empty on a one-off |
| What it depends on | An enum or a yes/no field of the same resource, which doesn’t itself depend on another |
| Not for | A relation (make it optional instead), a numbered or made field, or one with a default |
In the descriptor:
"cycle": { "kind": "enum", "options": ["monthly", "annually"], "when": { "kind": "recurring" } }Phone numbers
Section titled “Phone numbers”phone:tel takes a real phone number of any country. phone:tel(UG) takes Ugandan numbers only, and any country’s code works there: tel(GB), tel(US). Each is checked against libphonenumber, Google’s record of how numbers look in each country, by the dashboard and by Laravel, whichever way the number arrives: the form, the API, “Add several”, a CSV import or a public form.
In the dashboard, tel has a picker for the country’s code, starting at NEVELA_PHONE_COUNTRY if the app sets it and at the viewer’s own otherwise, and tel(UG) keeps it fixed at +256.
Every number is kept one way, whichever way it was written. So 0772 123456 and +256772123456 are the same number to a unique field, and the seeder makes real numbers.
| Sent | Kept |
|---|---|
0772 123456 |
+256772123456 |
772123456 |
+256772123456 |
+256 772 123 456 |
+256772123456 |
(0414) 123-456 |
+256414123456 |
+254 712 345678 |
refused: “Enter a Ugandan number, such as 0772 123456 or +256 772 123456.” |
0772 123456 ext 2 |
refused: an extension has nowhere to go in +256772123456 |
A tel field without a country needs to know where a number with no + is from. Say so once for the app, in apps/api/.env:
NEVELA_PHONE_COUNTRY=UGThen 0772 123456 is read as Ugandan, +44 7400 123456 is still read as what it says, and the dashboard’s picker starts at Uganda. Without it, a number needs its +. Run nevela generate after changing it.
In the descriptor:
"phone": { "kind": "string", "format": "tel", "country": "UG" }phone:tel[UG] and Grit’s phone:tel:UG mean the same. A number in the brackets is a length, as for a string: phone:tel(20).
Rich text
Section titled “Rich text”body:richtext is text with formatting. The dashboard gives it an editor with bold, italic, strikethrough, links, two sizes of heading, bullet and numbered lists, quotes, undo and redo, and the value is stored as HTML.
Nothing that is sent is trusted. Laravel parses the HTML and writes it out again with only the tags and attributes on a list, whichever way it arrived: the form, the API, “Add several” or a CSV import.
<p onclick="x()">Hi<script>alert(1)</script></p> is stored as <p>Hi</p>A tag that isn’t on the list goes and its words stay. A script, a style sheet or a frame goes with what is in it. A link keeps its address and nothing else, and only an http, https or mailto address, or one on your own site (/about). Plain text, from a spreadsheet for example, becomes a paragraph.
The same cleaning is done when a record is read, so HTML that reached the table some other way is never sent out as it is. What the API returns is safe to put on a page.
| The list | rich_text in config/nevela.php. It matches the editor’s toolbar. Add a tag only if you would let a stranger put it on your page. |
| Length | 65,535 characters unless you give one: body:richtext(20000). It counts the HTML that is stored, tags included. |
| Empty | An editor that was opened and left counts as empty, so a required field is still required. |
| In a table | The first words, as plain text. |
| Not offered | Sorting, filtering, search, and a cell in “Add several”, which says so when the field is required. |
In the descriptor it is a text field with "format": "rich".
Relations and files
Section titled “Relations and files”category:belongsTo(Category) links a record to one of another resource. It is stored as category_id and called categoryId in the API. See Relationships.
Coming from Grit or Flare
Section titled “Coming from Grit or Flare”The spellings those two use are understood, so you can type what you know:
| You write | Nevela reads it as |
|---|---|
image:file:image (Grit) |
image:image |
image:file:[image] (Flare) |
image:image |
docs:file:[pdf, image] |
docs:file(pdf|image) |
gallery:files[image] (Grit) |
gallery:files(image) |
category:belongs_to:Category |
category:belongsTo(Category) |
status:enum:draft|live |
status:enum(draft|live) |
phone:tel[UG], phone:tel:UG |
phone:tel(UG) |
email:email:unique, phone:tel:UG:unique |
email:email!, phone:tel(UG)! |
status:select[draft, sent], size:radio[s, m] |
status:enum(draft|sent), size:enum(s|m) |
terms:select[net15="Net 15", net30="Net 30"] |
terms:enum(net15=Net 15|net30=Net 30) |
sent:toggle, sent:checkbox |
sent:boolean |
stars:rating:10 |
stars:rating(10) |
country:country:UG |
country:country(UG) |
notes:textarea |
notes:text |
image:image takes a picture and optimises it as it arrives; image:image(product) names the profile it is optimised with. manual:file(pdf|document) takes other files and stores them as they are. Neither can be unique, sorted by or filtered on. See Files and images.
integer, bool and decimal are accepted as other spellings of int, boolean and money.
Anything else after a type is refused and says so, rather than being left out: email:email(work) is a mistake, and a field that quietly isn’t what you wrote is a worse one.
A string or text can have a length of its own: excerpt:string(500), body:text(100000). The column, the validation and the dashboard’s form all use it. A text longer than 65,535 is stored as longText.
Every resource also has id, createdAt and updatedAt. You do not declare them, and those names are reserved. The id is a UUID unless the resource was made with --id=int or adopted from a table with integer ids; either way it is a string in the API.