# Ordering

> The sort position of a record within its set.

Source: CBX documentation, version 4.0 preview (unreleased). Canonical page: https://docs.configbox.at/docs/4.0-preview/technical/property-types/ordering. Last updated 2026-07-27.

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