Vooraf
Een formulier in Skryv is een definitie die het platform pas bij het openen omzet naar een scherm. Voor elk veld kiest het platform een standaardweergave op basis van het type: een tekstveld, een datumkiezer, een adresveld. Soms volstaat die standaardweergave niet. Een adresveld moet bijvoorbeeld meteen nagaan of de gemeente de aanvraag ondersteunt, en op basis daarvan andere velden invullen. Dan bouw je een eigen formuliercomponent.
Een eigen formuliercomponent is het punt waar developer en configurator elkaar ontmoeten:
-
Developer bouwt het component en registreert het onder een naam.
-
Configurator gebruikt die naam in Skryv Studio, bij elk formulierveld waar het component nodig is.
Eigen formuliercomponenten registreer je in de frontoffice of de backoffice. Hoe je die webinterfaces in het algemeen aanpast, lees je op Frontoffice aanpassen en Backoffice aanpassen.
Je kunt eigen formuliercomponenten bouwen in beide frontends: als React-component in de frontoffice en als AngularJS-component in de backoffice. Stap 1 tot 5 beschrijven de frontoffice. De verschillen voor de backoffice lees je onder In de backoffice.
Stap 1: bouw het component
Een eigen formuliercomponent is een React-component in de map src/customizations/components van de module frontoffice. Groepeer formuliercomponenten bij voorkeur in een eigen submap, bijvoorbeeld components/form.
Vertrek van een platformcomponent
Je bouwt een formuliercomponent zelden van nul op. Meestal vertrek je van het platformcomponent dat het dichtst bij je doel ligt, en hergebruik je de hulpfuncties en basiscomponenten ervan. Voor een veld dat op een adres voortbouwt, gebruik je bijvoorbeeld de hulpfunctie useAddress en de invoercomponenten van de VO-stijl:
import React from "react";
import useAddress, {
containerComponentProps,
} from "@skryv/core-react/src/components/form/editor/AddressInput/addressInputHelpers";
import EditorComponent from "@skryv/core-react-vo/src/components/form/components/wrappers/EditorComponent/EditorComponent";
import InputField from "@skryv/core-react-vo/src/components/base/InputFields/InputField/InputField";
function MijnappAdresMetGemeenteinfo(props) {
const {
id,
fields = {},
label,
isRequired,
readOnly,
help,
helpInLine,
errorMessages,
warningMessages,
} = useAddress(props, EditorComponent);
return (
<InputField
id={id}
label={label}
isRequired={isRequired}
help={help}
helpInLine={helpInLine}
errorMessages={errorMessages}
warningMessages={warningMessages}
>
{readOnly ? renderAlleenLezen(fields) : renderBewerkbaar(fields)}
</InputField>
);
}
MijnappAdresMetGemeenteinfo.propTypes = containerComponentProps;
export default MijnappAdresMetGemeenteinfo;
renderAlleenLezen en renderBewerkbaar schrijf je zelf, zie verder.
De code van de platformcomponenten vind je na npm install in node_modules/@skryv/core-react en node_modules/@skryv/core-react-vo. Bekijk daar hoe het standaardcomponent werkt voor je erop voortbouwt.
Deze hulpfuncties en basiscomponenten importeer je uit interne paden van het platform (.../src/...). Die paden zijn geen vast contract en kunnen bij een platformupgrade wijzigen. Controleer bij elke upgrade de release notes, en test je eigen formuliercomponenten na elke upgrade.
Wat het component van het platform krijgt
Via de props en useAddress heeft je component toegang tot:
|
Wat |
Waarvoor |
|---|---|
|
|
De deelvelden van het veld, zoals |
|
|
Andere velden in hetzelfde fieldset. Je leest ze met |
|
|
De formulierconfiguratie van de frontoffice, waaronder de eigen requests in |
|
|
Hoe het veld zich moet gedragen en welke meldingen het moet tonen. |
Voorzie twee weergaven
Een formulier wordt niet alleen ingevuld, maar ook bekeken nadat het ingediend is. Je component moet dus twee weergaven voorzien:
-
Een bewerkbare versie, wanneer
readOnlyniet gezet is. -
Een alleen-lezen versie, die de ingevulde waarden als tekst toont, of ‘n.v.t.’ als alles leeg is.
Vul andere velden in
Een eigen formuliercomponent kan andere velden in hetzelfde fieldset invullen, bijvoorbeeld met gegevens die het opgehaald heeft:
const nisCode = props.manipulator.propertyManipulators.nisCode;
const extraInfo = props.manipulator.propertyManipulators.extraInfo;
nisCode.value = gemeenteinfo.nisCode;
// optioneel veld: niet elk formulier heeft het
if (extraInfo) {
extraInfo.value = gemeenteinfo.extraInfo;
}
Wordt de invoer gewijzigd, maak de afgeleide velden dan eerst leeg met .clear(), voor je nieuwe gegevens ophaalt. Zo blijft er geen verouderde waarde staan als het ophalen mislukt.
Je component verwacht dat de velden die het gebruikt, ook in de formulierdefinitie staan, met exact dezelfde naam. Ontbreekt een veld, dan faalt het component bij het openen van het formulier. Controleer daarom elk veld dat niet in alle formulieren voorkomt, voor je het gebruikt, en documenteer welke velden je component verwacht (stap 4).
Stap 2: registreer het component
Je registreert het component in src/index.js, op het form-object van het platform, onder een naam:
import { form } from "@skryv/core-react";
import MijnappAdresMetGemeenteinfo from "./customizations/components/form/MijnappAdresMetGemeenteinfo";
form.addCustomComponent("mijnappAdresMetGemeenteinfo", MijnappAdresMetGemeenteinfo);
Het form-object geef je daarna mee in de ketting waarmee de frontoffice opstart, met .customize(form).
Eén component, meerdere varianten
Heb je hetzelfde component nodig met een kleine variatie, bijvoorbeeld per dossiertype? Maak dan een kleine wrapper die een vaste prop meegeeft, en registreer elke wrapper onder een eigen naam:
export function MijnappAdresVoorPremie(props) {
return <MijnappAdresMetGemeenteinfo {...props} dossierType="premie" />;
}
export function MijnappAdresVoorAttest(props) {
return <MijnappAdresMetGemeenteinfo {...props} dossierType="attest" />;
}
form
.addCustomComponent("mijnappAdresVoorPremie", MijnappAdresVoorPremie)
.addCustomComponent("mijnappAdresVoorAttest", MijnappAdresVoorAttest);
Kies een naam met een app-prefix
De naam is wat de configurator in Studio invult. De formuliercomponenten van het platform beginnen met skr, bijvoorbeeld skrHiddenComponent. Geef je eigen componenten een prefix van je applicatie, zoals mijnapp. Zo ziet een configurator in een formulierdefinitie meteen welke componenten van het platform komen en welke van de applicatie, en vermijd je een botsing met een platformcomponent dat later onder dezelfde naam verschijnt.
De naam is een contract met de formulierdefinities. Hernoem je het component in de code, dan moet je de naam ook aanpassen in elk formulier dat het gebruikt. Spreek een nieuwe naam daarom altijd af met de configuratoren van de applicatie.
Stap 3: laat het component gegevens ophalen (optioneel)
Moet je component gegevens ophalen uit de back-end, bijvoorbeeld informatie op basis van een postcode? Dan maak je daarvoor een eigen request beschikbaar via de formulierconfiguratie.
Maak het request beschikbaar
Je schrijft in src/index.js een functie die een actie in je eigen store aanroept en de gegevens uit het antwoord teruggeeft. Die functie zet je onder customRequest in form.setFormConfig(...):
import store from "./customizations/store";
import { fetchGemeenteinfo } from "./customizations/store/actions";
function haalGemeenteinfoOp(postcode, dossierType) {
return store
.dispatch(fetchGemeenteinfo(postcode, dossierType))
.then(({ api }) => api.response.data);
}
form.setFormConfig({
customRequest: {
haalGemeenteinfoOp,
},
});
De actie spreekt een REST-endpoint in de back-end aan. Dat endpoint bouw je als backend-extensie, zie Backend-extensie bouwen. Haalt het endpoint de gegevens zelf bij een externe dienst op, dan gebeurt dat via een connector.
Roep het request aan vanuit het component
In het component vind je het request terug in props.config.customRequest:
const haalGemeenteinfoOp = props.config.customRequest.haalGemeenteinfoOp;
useEffect(() => {
nisCode.clear();
setFout(undefined);
if (!postcode || postcode.length !== 4) {
return;
}
haalGemeenteinfoOp(postcode, props.dossierType)
.then((gemeenteinfo) => {
nisCode.value = gemeenteinfo.nisCode;
})
.catch((error) => {
setFout(error?.data?.code ?? "onbekend");
});
}, [postcode, props.dossierType, haalGemeenteinfoOp, nisCode]);
Behandel elke mislukte aanroep als een fout, ook als het antwoord geen herkenbare foutcode bevat. Een time-out van een gateway geeft bijvoorbeeld een HTML-pagina terug in plaats van een foutmelding. Behandel je dat als een geldig, leeg antwoord, dan toon je de burger een inhoudelijke conclusie ("deze gemeente doet niet mee") terwijl er alleen een technisch probleem is. Toon in dat geval een melding dat het systeem de gegevens nu niet kan nagaan, en dat de burger het later opnieuw kan proberen.
Zet de meldingen die je component toont, in de vertalingen van de frontoffice, en niet als vaste tekst in de code.
Stap 4: gebruik het component in een formulier
De configurator koppelt het component in Skryv Studio aan een formulierveld. Bij de eigenschap Visualisatie van het veld kiest hij Andere, en vult hij de naam van het component in. Zie Algemene eigenschappen formulier elementen.
In de JSON-definitie van het formulier wordt dat de eigenschap customComponentName. Een vereenvoudigd voorbeeld:
{
"type": "fieldset",
"name": "adresWoning",
"label": "Adres van de woning",
"customComponentName": "mijnappAdresVoorPremie"
}
Gebruik exact dezelfde naam als bij de registratie in stap 2. Neem in hetzelfde fieldset ook de velden op die het component leest of invult, met exact de namen die het verwacht.
Een configurator ziet in Studio niet welke eigen componenten er bestaan, en ook niet welke velden ze verwachten. Houd daarom per applicatie een lijst bij van de eigen formuliercomponenten, met per component: de naam, het veldtype waarvoor het bedoeld is, de velden die in het fieldset moeten staan en wat het component doet. De README van de repository is daar een goede plaats voor.
Stap 5: test het component
-
Unittests: test het component met Jest, zoals de andere frontofficecomponenten. Je voert ze uit met
npm testin de modulefrontoffice. -
In de frontoffice: start de applicatie lokaal en open een formulier waarin het component gebruikt wordt. Controleer minstens:
-
de bewerkbare en de alleen-lezen weergave
-
een formulier waarin een optioneel veld ontbreekt
-
een leeg antwoord, een foutmelding en een time-out van de back-end
-
-
Na elke platformupgrade: test je eigen formuliercomponenten opnieuw, omdat ze op interne bouwstenen van het platform steunen.
In de backoffice
Ook in de backoffice kun je een eigen formuliercomponent bouwen. Het principe is hetzelfde als in de frontoffice: je bouwt een component, registreert het onder een naam met een app-prefix, en de configurator verwijst naar die naam met customComponentName. Het verschil zit in de technologie. De backoffice draait op AngularJS (@skryv/core-ng1), dus je component is een AngularJS-component, zoals de andere componenten van de backoffice. Hoe je die bouwt, lees je op Backoffice aanpassen.
Resultaat
Je component is geregistreerd in de frontoffice onder een naam met een app-prefix. Configuratoren kunnen het in Skryv Studio aan formuliervelden koppelen. Het toont een bewerkbare en een alleen-lezen weergave, haalt waar nodig gegevens op via een eigen request, en onderscheidt een technische fout van een geldig antwoord.