{shuffle:ids:limit}

Description

Randomly reorders a dash-separated list of values and joins them back with dashes. Each segment is trimmed; empty segments and a bare zero are dropped before shuffling (the same list parsing as ids, reverse and sort). With the optional limit it returns only the first N values of the shuffled list, so it doubles as a random picker. The order is random on every render and the command is never cached, so its raw output is non-deterministic; wrap it in count or sort when you need a stable, testable result. Typical use: randomise a set of item ids before passing them to a view, or pick one random id with a limit of 1.

Parameters

ids required default (empty string - returns empty)

A dash-separated list of values to randomise, usually a list of item ids (for example produced by ids). Each value is trimmed; empty segments and a bare zero are dropped before shuffling. A list with one value returns that value unchanged; an empty list returns an empty string.

limit optional default (none - returns all)

Optional maximum number of values to return after shuffling. When set to a positive integer N, only the first N values of the shuffled list are returned, which turns shuffle into a random picker (limit 1 returns one random value). When omitted, zero or empty, the whole shuffled list is returned.

Examples

test{count:{shuffle:0-1-2}}

Expected2

Actual2

List parsing drops empty segments and a bare zero before shuffling, so 0-1-2 is only two values - a common trap when ids could be zero.

test{count:{shuffle:a-b-c-d-e}}

Expected5

Actual5

Shuffling only reorders the values, so wrapping the result in count gives the original length back regardless of the random order.

test{shuffle:}

An empty list shuffles to an empty string.

test{count:{shuffle:a-b-c-d-e:2}}

Expected2

Actual2

With a limit of 2, shuffle returns only the first two values of the shuffled list, so the count is exactly 2.

virtual{shuffle:red-green-blue-yellow:1}

Expectedblue (one random value)

Actualgreen

With limit 1 shuffle returns a single random value from the list - the idiom for picking one random item.

virtual{shuffle:{ids:9e1d2b9f88e3d6c3bf0eb967378610d6}:3}

Expected3 random item ids (e.g. ...-...-...)

Actuala65d19971986e750761f0efcd9a16b1b-3f6939e68470a2dbafdadf9a626a9dbf-ae1da231f3e5bc16496834a0711aa042

A real pattern: shuffle a slice id list and keep three, then feed the result to a view to show three random items. The three ids are random each render, so this is illustrative.

virtual{shuffle:Alpha-Beta-Gamma-Delta}

ExpectedGamma-Alpha-Delta-Beta (order is random)

ActualBeta-Gamma-Delta-Alpha

Returns the four values in a random order; the order changes on every render, so this is illustrative rather than asserted.

test{shuffle:Alpha}

ExpectedAlpha

ActualAlpha

A list with one value has only one possible order, so shuffle returns it unchanged - a deterministic, testable case.

test{sort:{shuffle:3-1-2}}

Expected1-2-3

Actual1-2-3

Sorting the shuffled list removes the randomness and proves no value was lost or added: the same three numbers always come back in order.

← All expressions