Fields
A field is one input in a block or a table. It is what a manager fills in, and what the template reads back.
Fields belong to a block or a table and are edited inside it — PageBlocks → Constructor, then the block or table, then its fields.
What a field row holds
| Setting | What it does |
|---|---|
| Label | What the manager sees above the input |
| Name | The key in the data. This is what the template reads: {$block->subtitle} |
| Type | Which input is rendered — see Field types |
| Default value | Prefilled in a new row |
| Width | Percent of the form row, 100 by default. Two fields at 50 sit side by side |
| Description | Hint under the input |
| Required | Blocks saving while empty |
| Tab | Which tab the field appears on |
| Order | Position among its siblings; drag and drop writes it |
Plus three flags that do nothing on the form and everything elsewhere:
| Flag | Where it shows |
|---|---|
| Searchable | The field joins the table's search |
| Filterable | The field appears in pbFilters and can be filtered over the API |
| Dependent | The field is only shown when another field satisfies a condition |
Name is the contract
Label can be renamed freely — it is only shown to a person. Name is the key the value is stored under, so renaming it after content exists orphans that content: the old key stays in data, the new one starts empty.
Nothing warns about this, because a rename and a new field look identical from the database's side. Decide the name before the field is filled in, and if you must rename later, migrate the data yourself.
There is no column behind a field
A field's value lives in the JSON column of its row, not in a column of its own. That is why adding a field needs no migration — and why a field name can be anything without the schema caring. See Models.
Dependent fields
A field with Dependent on is hidden until another field on the same form satisfies a condition. You pick the field it depends on and the operator.
This is for forms that branch: a delivery method select, and an address that only appears for courier delivery. Without it every option's fields are on screen at once and the manager has to know which ones apply.
Leave it off — or leave the dependency field empty — and the field is always visible.
Filterable is not the same as searchable
They look like two names for one thing and are not:
- Searchable feeds the free-text search over the table — one box, many fields.
- Filterable makes the field its own control: a select, a range, a date picker in
pbFilters, and a permittedfilter[...]key in the API.
A field that is filterable but not searchable is normal — a price, say. The reverse is just as normal for a long description.
An API filter needs this flag
"The filter does not work" over the API almost always means the field was never marked filterable. Nothing errors: an unknown filter key is ignored silently.
Width makes a form readable
Width is a percentage, so 50 + 50 puts two fields on one line, 33 gives three. A date next to a time, a city next to a postcode — a form where related fields sit together is read at a glance instead of scrolled.
Order and publishing
Drag and drop writes the order. An unpublished field disappears from the form but keeps its data, which is the safe way to retire a field: hide it, confirm nothing broke, delete it later.