Een bedrijfsregel schrijven

Doel

Een formulier laten reageren op wat degene die het invult aan het doen is: het veld Manager alleen tonen bij onkosten boven £100, Sluitingsdatum uitschakelen totdat de deal is gewonnen, Valuta standaard overnemen van het account.

Vereisten

• Je bent aangemeld als maker, met de oplossing van de tabel geopend.
• De tabel heeft de velden waar de regel over gaat, en — als je de regel aan één formulier wilt koppelen — dat formulier bestaat.

Wat een bedrijfsregel is, en wat niet

Een bedrijfsregel draait in de browser, op het formulier, en verandert hoe het formulier zich gedraagt. Hij kent vier werkwoorden: een veld tonen of verbergen, het in- of uitschakelen, het wel of niet verplicht maken, en een waarde instellen.

Hij beslist niet wat er mag worden opgeslagen. Iemand kan een regel uitzetten, een ander scherm gebruiken of de API rechtstreeks aanroepen, en het record wordt toch opgeslagen. Alles wat waar moet zijn over de gegevens, hoort in een plug-instap op de server, die draait wat de browser ook deed. Gebruik een bedrijfsregel om een formulier prettig te maken; gebruik een plug-instap om een regel echt te maken. Het is normaal om beide te willen, en ze worden bewust apart geschreven.

Stappen

1. Open het formulier waarvoor de regel is — de tabel, dan Formulieren, dan het formulier — en selecteer Gebeurtenissen in de werkbalk. De lijst toont elke regel die op dit formulier draait, ook regels die aan elk formulier van de tabel zijn gekoppeld.

2. Selecteer Nieuw. De regelontwerper opent.

3. Typ een weergavenaam. De logische naam vult zich in, voorafgegaan door het voorvoegsel van je uitgever, en ligt vast zodra de regel is opgeslagen.

4. Controleer het formulier. Het is al het formulier waar je vandaan kwam, en dat klopt bijna altijd — een regel gaat over velden, en de velden waar hij over gaat, zijn de velden die je voor je hebt. Zet het op Elk formulier voor iets wat moet gelden overal waar de tabel wordt getoond, zoals "verberg dit tenzij de status Goedgekeurd is". Een regel die aan elk formulier is gekoppeld, verschijnt nog steeds in de lijst Gebeurtenissen van elk formulier, met die markering.

5. Kies wanneer hij draait — één gebeurtenis per regel:

   • Als het formulier opent past de regel toe terwijl het record wordt weergegeven.
   • Als een veld verandert toont een veldkiezer. Kies een veld en het verschijnt als label; voeg er zoveel toe als de regel nodig heeft, en verwijder er een met de ✕ op het label.
   • Als het formulier wordt opgeslagen draait de regel tussen de druk op de knop en het schrijven, zodat hij iets kan invullen — of het opslaan kan tegenhouden met cancelSave, hieronder.

   Een regel zonder trigger draait nooit, dus Opslaan blijft uitgeschakeld totdat een regel voor een veldwijziging ten minste één veld heeft.

   Eén gebeurtenis per regel is bewust. Moet hetzelfde op twee momenten gebeuren — het gebruikelijke geval, "toon dit als de status afgewezen is", wat moet kloppen als het formulier opent en telkens als de status verandert — schrijf dan twee regels die één oplossingsscript importeren, elk twee regels lang. De logica wordt één keer geschreven; waar de twee momenten echt verschillen, vraagt het script eventType() en beslist het zelf. Meerdere triggers op één regel zouden die beslissing nergens neerleggen: niets op het scherm zou zeggen welke helft van het script bij welke gebeurtenis hoorde.

6. Schrijf het script in de editor. Die onderstreept fouten terwijl je typt, vult de functies van het platform aan en toont de argumenten van elke functie zodra je het openingshaakje typt. Het oog in de bovenhoek van de editor opent Wat een script kan aanroepen boven de code.

7. Laat Ingeschakeld aangevinkt, of vink het uit om de regel te bewaren zonder hem te laten draaien.

8. Selecteer Opslaan.

Wat een script kan aanroepen

Aanroep	Wat het doet
getValue(field)	De huidige waarde van het veld op het formulier.
setValue(field, value)	Stelt een veld op het formulier in.
setVisible(field, visible)	Toont of verbergt een veld.
setDisabled(field, disabled)	Maakt een veld alleen-lezen, of niet.
setRequired(field, required)	Maakt een veld verplicht, of niet.
eventType()	"OnLoad", "OnChange" of "OnSave" — welke gebeurtenis er draait.
changedField()	Het veld waarvan de wijziging een OnChange heeft veroorzaakt, anders "".
isNewRecord()	true totdat het record één keer is opgeslagen. Gebruik het om een veld te vergrendelen dat één keer wordt gekozen en daarna blijft, zoals het type van een activiteit.
cancelSave(message)	Alleen bij opslaan: stopt het opslaan van dit formulier en toont het bericht.
isEmpty(value)	Of een waarde niet is ingevuld. Lege tekst en helemaal niets zijn leeg; 0 en false zijn waarden die iemand heeft gekozen.

Een veld wordt aangeduid met zijn logische naam (par_amount), niet met zijn weergavenaam.

Een veld zonder inhoud leest als lege tekst, dus getValue("par_currency") == "" is de controle voor "nog niet ingevuld" — zo werkt het valutavoorbeeld hieronder. Voor een getal, een datum of een zoekveld is er geen lege tekst om mee te vergelijken, dus vraag dan isEmpty(getValue("par_due")). Dat gebruikt dezelfde definitie van leeg als de eigen verplicht-controle van het formulier, en daarom kan een regel geen standaardwaarde geven aan een veld dat het formulier net als ingevuld heeft geaccepteerd.

getValue en setValue worden precies zo gespeld en gedragen zich precies zo als in een plug-instap op de server, dus logica die je één keer uitwerkt, leest aan beide kanten hetzelfde.

Een getalveld leest als een getal — 1200.5, niet "1200.5" — ook terwijl het wordt getypt, en een niet-ingevuld getalveld leest nog steeds als leeg. Dat doet ertoe zodra je een eigen functie schrijft: func needsApproval(amount: number) accepteert geen stuk tekst, en de fout is dan Function overload for needsApproval not found. in plaats van iets over typen. Declareer een bedrag dus als number, niet als int — een Decimaal-kolom bevat 1200.50, en een parameter voor hele getallen weigert dat — en vervang een leeg vak door nul voordat je ermee rekent:

func claimAmount(): number {
  var raw = getValue("par_amount");
  if (isEmpty(raw)) { return 0; }
  return raw;
}

…en alles wat een oplossingsscript exporteert. Als dezelfde paar regels in meerdere regels opduiken, verplaats ze dan naar een oplossingsscript en importeer het door import 'par_expense_helpers'; bovenaan de regel te typen — de editor vult de naam aan, en weet vanaf dat moment wat de module exporteert.

Keuzes, en een sectie tonen voor een ervan

Een keuze leest als haar getal, de waarde die de optie heeft gekregen (110000001), of het formulier nu net is geopend of iemand haar net heeft gekozen. Vergelijk haar dus met een getal, niet met tekst:

if (getValue("pw_type") == 110000001) { setVisible("pw_to", true); }

Voorheen las een keuze die iemand net had gemaakt als tekst ("110000001"), en de vergelijking hierboven werkte na de eerste keuze stilletjes niet meer. Een regel die met tekst tussen aanhalingstekens vergeleek, moet de aanhalingstekens kwijt.

Wil je een sectie alleen voor één keuze tonen, verberg dan de velden erin. Een sectie waarvan alle velden verborgen zijn, verdwijnt, titel en al, en komt terug als een regel een van die velden weer toont. Zo toont het activiteitenformulier van Sales een sectie E-mail voor een e-mail en een sectie Telefoongesprek voor een gesprek.

Wil je een veld één keer laten kiezen, schakel het dan uit als het record niet nieuw is:

setDisabled("pw_type", !isNewRecord());

Als een nieuw record wordt opgeslagen, draaien de regels die bij het laden draaien opnieuw, dus het veld wordt meteen vergrendeld. Zoals elke regel houdt dit alleen het formulier tegen. Wil je ook voorkomen dat de API of een import het veld wijzigt, schrijf dan ook een plug-instap op de server.

Het opslaan tegenhouden

Een regel die draait als het formulier wordt opgeslagen, kan het opslaan weigeren:

if (getValue("par_status") == "rejected" && getValue("par_reason") == "") {
  cancelSave("Give a reason before rejecting this claim.");
}

Het opslaan stopt, je bericht verschijnt bovenaan het formulier, en er gaat niets verloren — het formulier blijft open met alles wat erin is getypt.

Dit is nog steeds geen afdwinging. Het houdt dit formulier, in deze browser tegen: de API, een import, een aangepaste app en elk ander formulier zonder de regel slaan het record hoe dan ook op. Het bestaat omdat "laat me dit niet half ingevuld indienen" het zeggen waard is op het formulier — maar als het iets is wat waar moet zijn over de gegevens, schrijf dan ook een plug-instap op de server.

Een voorbeeld

Toon het managerveld, en maak het verplicht, alleen bij onkosten boven 100 — bij het laden en telkens als het bedrag verandert:

var over = getValue("par_amount") > 100;
setVisible("par_manager", over);
setRequired("par_manager", over);

Merk op dat het in beide richtingen zegt wat er waar moet zijn. Een regel die een veld alleen maar toont, laat het op het scherm staan nadat het bedrag weer is gezakt, omdat niets heeft gevraagd het weer te verbergen.

Twee regels op één formulier

Elke ingeschakelde regel die bij het formulier en de gebeurtenis past, draait, in volgorde van logische naam, elk met eigen variabelen. Ze delen de waarden op het formulier, dus een regel die een veld instelt, wordt gezien door de regels erna. Spreken twee regels over hetzelfde veld, dan wint de laatste — dat is stabiel, maar het is toeval en geen ontwerp, dus geef de voorkeur aan één regel per veld.

Een regel kan niet eeuwig draaien

Elke regel draait met een budget, en een regel die dat overschrijdt, wordt gestopt en onder zijn eigen naam gemeld. Er zijn drie grenzen, en elk vangt een andere fout:

Het stopt	Wanneer
een lus die nooit eindigt	while (true), of een voorwaarde waaraan nooit helemaal wordt voldaan
een regel die gewoon te veel doet	hij is na een halve seconde nog bezig
een functie die zichzelf eindeloos aanroept	ze is honderd aanroepen diep zonder einde in zicht

Het formulier blijft werken, de persoon houdt wat hij aan het typen was, en het bericht noemt de regel en de regel in de code. De lus in een try zetten helpt niet — het budget is niet iets wat een script kan opvangen.

Je komt dit niet per ongeluk tegen: de grootste regel in een voorbeeld gebruikt ruim minder dan een honderdste van het budget. Kom je het wel tegen, dan zit er een fout in de regel — meestal een while waarvan de body de voorwaarde nooit verandert.

Een opmerking over het vergelijken van waarden. == vergelijkt binnen één soort: twee getallen, twee stukken tekst, twee waar/onwaar-waarden. Twee verschillende soorten zijn nooit gelijk — 1 == "1" is onwaar — en niets is gelijk aan niets, dus een niet-ingesteld veld is niet gelijk aan "". Daarom leest een veld zonder waarde als lege tekst, en daarom bestaat isEmpty() voor getallen en datums.

Problemen oplossen

• Een regel die nooit lijkt te draaien. Controleer of hij is ingeschakeld, of zijn formulierkoppeling overeenkomt met het formulier waar je naar kijkt, en of zijn trigger het veld bevat dat je wijzigt.
• "BS Lang script is invalid: …" bij het opslaan — het script kan niet worden geparsed. De editor onderstreept dezelfde fout; het bericht noemt de regel.
• "Form '…' was not found on '…'." — de regel is gekoppeld aan een formulier dat de tabel niet heeft. Kies er een uit de lijst, of koppel aan elk formulier.
• Een rood bericht bovenaan een formulier in de app, met de naam van een regel. De regel is tijdens het draaien op een fout gestuit. Het formulier blijft werken; de regel is gestopt waar hij misging.
• Onderstrepingen onder getValue — de editor meldt de eigen functies van het platform niet meer als ongedefinieerd. Zie je dit, dan roept het script iets aan wat niet in de lijst hierboven staat.

Gerelateerde scenario's

• Een formulier maken.
• Een veld verplicht of alleen-lezen maken — de vaste versie van hetzelfde idee, voor als het antwoord nooit van het record afhangt.