📜 JavaScript guidelines

Richtlijnen voor client-side scripting binnen Dataverse

← Terug naar Develop

1. Introductie

JavaScript wordt binnen Dataverse gebruikt voor client-side business logica en UI-interactie binnen model-driven apps.

Het biedt flexibiliteit voor complex form gedrag, maar introduceert ook meer technische complexiteit en onderhoud.

👉 Gebruik JavaScript voor complexe UI logica en interactie die niet met standaard configuratie mogelijk is.

2. Doel

JavaScript wordt toegepast voor:

  • Complexe validaties
  • Dynamisch UI gedrag
  • Form interacties (onLoad, onChange)
  • Integratie met APIs / services

3. Opbouw van JavaScript

JavaScript wordt als webresource ontwikkeld en gekoppeld aan formulieren binnen Dataverse.

Stappen

  1. Maak een JavaScript webresource aan
  2. Koppel het script aan het formulier
  3. Registreer events (onLoad, onSave)
  4. onChange events worden in code verwerkt
  5. Gebruik executionContext voor toegang tot het formulier
  6. Implementeer logica via functies en helper libraries
  7. Publiceer en test de oplossing

Bestandsopbouw

Gebruik per entiteit één scriptbestand:

											
account.js    // alle account logica  
contact.js    // alle contact logica  
lead.js       // alle lead logica
  • Gebruik één script per entiteit als standaard
  • Structureer logica intern (form, validation, business, UI)
  • Splits alleen bij hogere complexiteit

Opbouw van JavaScript

  • Functions → logica
  • Events → triggers (onLoad, onChange, onSave)
  • onChange events worden in de onLoad geconfigureerd
  • Namespaces → structuur en herbruikbaarheid
👉 Gebruik namespaces (bijv. brenke.core) om globale vervuiling te voorkomen.

Algemene principes

  • Houd scripts modulair en herbruikbaar
  • Schrijf zelfverklarende code met duidelijke namen
  • Gebruik waar mogelijk configuratie boven code (bijv. Business Rules)
  • Voorkom globale variabelen
  • Gebruik altijd "use strict"; 
											
"use strict";

Gebruik van brenke.core

Gebruik herbruikbare helper functies via de core library.

Field operations

											
brenke.core.field.getValue(formContext, "fieldname");
brenke.core.field.setValue(formContext, "fieldname", value);
brenke.core.field.setRequired(formContext, "fieldname", true);

UI helpers

											
brenke.core.ui.showTab(formContext, "tabname", true);
brenke.core.ui.showSection(formContext, "tabname", "sectionname", false);

Validaties

											
brenke.core.validationDutch.isIBAN("NL91ABNA0417164300");
brenke.core.phone.isValid("+31101234567", "NL");
brenke.core.postcode.isValid("1234AB", "NL");

Notifications

											
brenke.core.notifier.showFormNotification(formContext, "Bericht", "INFO");
brenke.core.notifier.showFieldNotification(formContext, "Ongeldige waarde", "ERROR", "fieldname");
brenke.core.notifier.clearForm(formContext);

Logging

											
brenke.core.logger.info("Info message");
brenke.core.logger.warn("Warning message");
brenke.core.logger.error("Error message");
brenke.core.logger.logError("Gedetailleerde fout", err, formContext);
👉 Gebruik centrale libraries voor consistent gedrag en onderhoudbaarheid.

4. Wanneer gebruik je JavaScript

✅ Wel gebruiken
  • Complexe veldafhankelijkheden
  • Dynamische UI logica
  • Geavanceerde validaties
  • Context-afhankelijk gedrag op formulieren
⚠️ Beperkingen
  • Alleen client-side (geen server validatie)
  • Afhankelijk van browser en client gedrag
  • Moeilijker te beheren bij groeiende complexiteit
❌ Niet gebruiken voor
  • Eenvoudige validaties → gebruik Business Rules
  • Procesautomatisering → gebruik Power Automate (Cloud Flows)
  • Server-side logica / transacties → gebruik Plugins
  • Geavanceerde UI componenten → gebruik PCF Controls
👉 Zie het besliskader: 🔀 Logic Implementation – techniek keuze

5. Decision flow (vereenvoudigd)

  • Eenvoudige UI logica → Business Rule
  • Complexe UI logica → ✅ JavaScript
  • Custom UI component → PCF Control
  • Proces → Cloud Flow
  • Backend logica → Plugin / API

6. Testing

  • Test alle event triggers (onLoad, onChange, onSave)
  • Controleer afhankelijkheden tussen velden
  • Test foutscenario’s
  • Controleer gedrag in verschillende formulieren
👉 Test altijd interactie tussen meerdere scripts en platform logica.

7. Performance

  • Minimaliseer get/set calls
  • Cache waarden
  • Beperk logica in onLoad
  • Vermijd onnodige DOM interactie

8. ALM & Deployment

JavaScript wordt opgeslagen in webresources en gedeployed via solutions.

  • Onderdeel van solutions
  • Versiebeheer essentieel
  • Altijd testen na deployment
  • Afhankelijkheden met formulieren en events
👉 JavaScript heeft directe impact op UX → regressietesten zijn cruciaal.

9. Richtlijnen

Eenvoud

  • Houd functies klein en overzichtelijk
  • Vermijd complexe nested logica

Naming

  • Gebruik duidelijke en consistente namen

Voorbeelden:

  • Account_OnLoad
  • Contact_ValidateEmail

Structuur

  • Gebruik namespaces
  • Splits logica per verantwoordelijkheid

Onderhoudbaarheid

  • Voorkom duplicatie
  • Gebruik helper libraries

10. Veelgemaakte fouten

✘ Gebruik van globale variabelen

✘ Direct gebruik van Xrm.Page

✘ Duplicatie van logica

✘ Te grote scripts zonder structuur

11. Troubleshooting

  • Controleer of events correct zijn gekoppeld
  • Gebruik browser console (F12)
  • Controleer errors in logging
  • Check afhankelijkheden met andere scripts

12. Voorbeeld

Scenario:

  • Bij wijziging van land → telefoonnummer formatteren

Implementatie: 

																				
function onCountryChange(executionContext){
  var formContext = executionContext.getFormContext();
  var phone = brenke.core.field.getValue(formContext,"phone");
}

13. Samenvatting

  • Complexe UI logica → JavaScript
  • Custom UI → PCF Controls
  • Gebruik structuur en namespaces
  • Altijd testen binnen ALM
✅ Flexibel en krachtig ❌ Complexer in onderhoud