{finduniq:string:field_id:unique_slices:ignore_item_id}

Description

Returns a value that is unique within one field across the given slice or slices. finduniq searches those slices for an item whose field equals the value; if one exists it appends 2, then 3, and so on (with no separator, so name becomes name2) until the value is free, and returns that. With no slices it returns the value unchanged. An item id can be passed as ignore_item_id so the item being saved does not collide with itself. If the value is empty it returns a fresh random id. The search covers active, expired, pending and holding items. This drives the Unq field inserter, which keeps a field unique on every save.

Parameters

string optional

The candidate value to make unique. If empty or whitespace, finduniq skips the slice check and returns a fresh random 32-character id instead.

field_id optional

The field whose values must stay unique, given as a field id such as headline........ . finduniq compares the candidate against this field across the listed slices.

unique_slices optional

One or more slice ids (dash-joined) to search for a conflict. If empty, finduniq performs no check and returns the string unchanged. The search spans active, expired, pending and holding items.

ignore_item_id optional

A long item id to exclude from the conflict check. If the only matching item is this one, the value counts as free and is kept. Used so an item can keep its own value on re-save without bumping the number.

Examples

test{finduniq:Brandnew:headline........:9e1d2b9f88e3d6c3bf0eb967378610d6}

ExpectedBrandnew

ActualBrandnew

No item in the slice has Brandnew in the headline field, so the value is already unique and is returned verbatim.

test{finduniq:Gamma:headline........:9e1d2b9f88e3d6c3bf0eb967378610d6}

ExpectedGamma2

ActualGamma2

An item with headline Gamma already exists, so finduniq tries Gamma2, finds it free, and returns it. The number is appended with no separator (Gamma2, not Gamma-2).

test{finduniq:Gamma:headline........}

ExpectedGamma

ActualGamma

With the third parameter (unique_slices) left empty, finduniq does not query anything and returns the string unchanged, even though a Gamma item exists.

test{finduniq:Gamma:headline........:9e1d2b9f88e3d6c3bf0eb967378610d6:5726c2c6b035d7aab450d1794e9e90d7}

ExpectedGamma

ActualGamma

The only item that matches Gamma is the one whose id is passed as ignore_item_id, so it is treated as free and Gamma is kept. This is how a record can keep its own value on re-save without bumping the number.

virtual{finduniq::headline........:9e1d2b9f88e3d6c3bf0eb967378610d6}

Expected(a random 32-character hex id, e.g. 3f6a9c81b0d24e7f95a1c6e8d2b40f7c)

Actuald5534f02885d55c7434a34a57f55b911

When the first parameter is empty or whitespace, finduniq ignores the slice check and returns a fresh random 32-character id (via new_id). The exact value differs on every render, so this example is illustrative, not a fixed test.

← All expressions