🧱 Field Helper

📖 Introductie

De Field Helper biedt een complete set utility functies voor het lezen, schrijven en manipuleren van veldwaarden binnen Dataverse forms.

---

📦 Functionaliteit

🔹 Basis

• getValue(formContext, name) → Haalt veldwaarde op
• setValue(formContext, name, value) → Zet veldwaarde
• clearValue(formContext, name) → Zet waarde op null
• hasValue(formContext, name) → Controle of veld gevuld is

✏️ Tekstvelden

• setTextValue(formContext, name, text) → Zet tekst (fallback leeg)
• setDefaultTextValue(formContext, name, text) → Alleen bij lege waarde
• copyTextField(formContext, source, target) → Kopieert tekst

🔢 Choice / OptionSet

• setChoice(formContext, name, value) → Zet numerieke optie
• getChoiceId(formContext, name) → Haalt ID (number)
• getChoiceText(formContext, name) → Haalt label (tekst)

🔗 Lookup velden

• setLookupValue(formContext, name, id, name, entityType)
• getLookupValue(formContext, name)
• getLookupId(formContext, name)
• getLookupText(formContext, name)
• getLookupEntityType(formContext, name)
• getEntityReference(formContext, name)
• copyLookupField(formContext, source, target)

⚙️ Default waarden

• setDefaultValue(formContext, name, value)
• setDefaultTextValue(formContext, name, text)
• setDefaultLookupValue(formContext, name, id, name, entityType)
• setDefaultLookupFromEnv(formContext, field, envVar)

✅ Validatie / gedrag

• setRequired(formContext, name, required)
• setRecommended(formContext, name, recommended)
• getBoolean(formContext, name)

⚡ Events

• addOnChange(formContext, name, handler)
• removeOnChange(formContext, name, handler)
• addOnChangeSafe(formContext, name, handler)

---

⚙️ Werking

De helper fungeert als abstractielaag bovenop de Dataverse formContext API.

1. Attributen ophalen

• formContext.getAttribute(name)

2. Type verwerking

• Tekstvelden → string
• OptionSets → number
• Lookup → array met object

3. Extra logica

• Default waarden (alleen bij lege velden)
• Safe event binding
• Lookup parsing

---

🔗 Lookup structuur

Een lookup wordt intern opgeslagen als array met object:

[
  {
    id: "GUID",
    name: "Display Name",
    entityType: "account"
  }
]

---

⚠️ Belangrijke aandachtspunten

• Null checks
  Voorkomt errors bij ontbrekende velden
• Lookup structuur
  Altijd array, ook bij één waarde
• OptionSets
  Werken met numerieke waarden (IDs)
• Default methods
  Overschrijven geen bestaande data
• Events
  addOnChangeSafe voorkomt dubbele handlers

---

💡 Voorbeelden

Waarde ophalen

const name = core.Field.getValue(formContext, "name");

Lookup zetten

core.Field.setLookupValue(
  formContext,
  "parentaccountid",
  "GUID",
  "Contoso",
  "account"
);

Default waarde zetten

core.Field.setDefaultValue(formContext, "name", "Nieuw record");

---

📊 Samenvatting