Skip to content
Nevela 0.33.1: New: customers get a shop in the mobile app, each sees only their own orders, and an administrator manages people and roles from the phone. Build it in the new drinks-app tutorial.A drinks app on the phone

Field types

Fields are written as name:type, separated by commas:

Terminal window
nevela resource Product --fields="name:string, sku:string!, price:money, notes:text?"
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.

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.

An order number, an invoice number or a ticket number is given by the app, one after another:

Terminal window
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 --fresh starts the numbers again.

An order item’s price is its product’s. Rather than type it, copy it:

Terminal window
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.

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 =:

Terminal window
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').

A money field is shown in a currency when one is set: for the whole app in apps/api/.env, or on the field.

Terminal window
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 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:

Terminal window
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: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=UG

Then 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).

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".

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.

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.