Ordering
- Version
- 4.0 preview
- Updated
The sort position of a record within its set.
Storage kind: column · Column: int unsigned, NOT NULL, default 0
Add one to any model whose records have a meaningful operator-controlled sequence — pages within a product, answers within a question. If the order is derived from the data (alphabetical, by date), do not add one: sort in the query instead.
Settings
| Setting | Meaning |
|---|---|
group | The property whose value defines the set being ordered within |
group is what makes ordering per-parent rather than global: pages order within their product,
answers within their question. Without it, every record of the model competes for positions in one
global sequence — right for a small global list, wrong for anything with a parent.
New records go to the end, in steps of 10
prepareForStorage() only acts on an insert. It reads the highest existing ordering — within
the group, when there is one — and assigns that plus 10.
The gap is deliberate: it leaves room to slot a record between two others by writing a value between
them, without renumbering the whole set. Do not assume positions are contiguous, sequential, or that
the first is 1 — read them as opaque sort keys and compare numerically.
On an update the property leaves the value alone, so a normal save never reorders anything.
Not nullable
An unsorted row is position 0, never unknown, and the ordering queries compare numerically. Update
3.6.5 made these NOT NULL with default 0, backfilling existing NULLs first.
Three ordering columns — cities, counties and examples — were plain signed int while every other
was int unsigned. That was a schema inconsistency rather than a decision, and the migration brought
them into line.
Notes
- The property renders a hidden input, not a visible control, and
usesWrapper()is false. The list cell is a drag handle (cb-sort-handle). - The list view's drag-to-reorder writes through
storeOrdering, not through a normal save — so reordering does not run the model's validation or the other properties'store()methods. - Dragging is refused while pagination is active; the handle carries the message explaining why. Sorting a page of a set whose neighbours are off-screen cannot produce a coherent order.
@see id.md
@see ../com_configbox_mvc_tasks.md — storeOrdering and the other base tasks