ExpandedReference class

A reference value as the gateway returns it when a record is read with expandReferences: true (find, findOne, findOwn on the API client; findRecords, findOneRecord on the Hub client).

Without the flag a reference field holds the stored id (or a list of ids when the field is multiple). With the flag every reference value becomes { "id": ..., "display": ... }:

• id — the stored id, unchanged.
• display — the target's display value, chosen by the schema's displayField: a user's displayName / email / …, a role's name, a term's title (the term name — a string or a { lang: text } map) or slug, or the named field of the target record (whatever type it has). null when the target is gone (a deleted record, term, user, …).

Nested forms and arrays are expanded in place, at any depth. The SDK does not decode records into classes, so this helper reads one value out of the decoded JSON:

final res = await api.database.find(
  collectionName: 'orders', expandReferences: true) as Map<String, dynamic>;
final first = jsonDecode(res['result'][0] as String) as Map<String, dynamic>;
final customer = ExpandedReference.maybeFrom(first['customer']);
print(customer?.displayText());              // "Jane Doe"
for (final tag in ExpandedReference.listFrom(first['tags'])) {
  print('${tag.id}: ${tag.displayText(language: 'en') ?? 'missing'}');
}

Constructors

ExpandedReference({required String id, Object? display})

const

ExpandedReference.fromJson(Map<String, dynamic> json)

Builds one from a decoded { "id": ..., "display": ... } object.

factory

Properties

display → Object?

The target's display value, or null when the target does not exist any more.

final

hashCode → int

The hash code for this object.

no setter, inherited

id → String

The stored id of the target (a user id usr_…, a role view id, a term id, a record id, a file id).

final

isMissing → bool

True when the target is gone — display is null.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

displayText({String? language}) → String?

The display value as one line of text.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toJson() → Map<String, Object?>

toString() → String

A string representation of this object.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

listFrom(Object? value) → List<ExpandedReference>

Reads a multiple reference (a list of expanded references) out of a decoded record value. A single expanded reference gives a one-item list; anything else (a plain id, a list of ids, null) gives an empty list.

maybeFrom(Object? value) → ExpandedReference?

Reads a single reference out of a decoded record value. Answers null when the value is not an expanded reference — for instance the plain id a read without expandReferences returns, or a missing field.