Skip to content

Developers Guide

Jump to bottom
Alexander Green edited this page Jun 21, 2024 · 9 revisions

In deze Developers guide zal er een beschrijving gegeven worden van de functionaliteiten die specifiek zijn aan het NL GOV profiel. Voor de algemene development guide voor de rest van ReSpec raden we aan om de officiële ReSpec development guide te gebruiken: https://github.com/speced/respec/wiki/Developers-Guide.

Configuratie files

ReSpec gebruikt een config file, binnen de Logius build wordt deze file gesplitst in 2 delen: document configs en organisatie configs. Deze files worden geladen in de index.html file met:
<script src="CONFIG_FILE_SRC" class="remove"></script>
Daarna worden alle configuratie files in één respecConfig object gezet:
<script>const respecConfig = { ...organisationConfig, ...config }</script>
Nieuwe files kunnen variabelen in oudere files overschrijven. Variabelen die aan de meest rechtse kant tussen de { } staan overschrijven eerdere variabelen.

Organisatie config

Deze config opties zijn variabelen die voor alle documenten binnen een organisatie gelijk zijn. Dit zijn bijvoorbeeld de organisatienaam of statuscodes. Het is handig om deze file centraal te hosten en dan in te laden. Hierdoor hoeft de file niet constant gekopieerd te worden en kunnen eventuele zeldzame aanpassingen (zoals een naamsverandering) globaal toegepast worden.

Document config

Deze configuratie opties zijn alleen relevant voor het document waarin ze gebruikt worden, denk bijvoorbeeld aan de status van het document, of er een label getoond moet worden en een lijst met schrijvers van het document.

Vertalingen

Om een document in verschillende talen te kunnen gebruiken worden er in de organisatie config verschillende vertalingen opgenomen:

labelText: {
    nl: {
      def: `Definitieve versie`,
      wv: `Werkversie`,
    },
    en: {
      def: `Definitive version`,
      wv: `Working version`,
    },

getIntlData() uit utils.js pakt dan de <html lang=""> tag uit de index file om te bepalen welke vertaling hij moet gebruiken.

Config warner

ReSpec geeft de mogelijkheid om errors en warnings aan gebruikers te geven. Omdat missende config opties het renderen van sommige onderdelen blokkeert, is het belangrijk dat een gebruiker weet als er een belangrijke config mist. Om het makkelijker te maken om bij te houden welke config opties vereist zijn is de config warner plugin gemaakt. De config warner plugin heeft 2 arrays: requiredConfigs en recommendedConfigs. Missende requiredConfigs geven een error, missende recommendedConfigs geven een warning. Beide linken in de "how to fix" automatisch naar de juiste config optie in de github wiki.

Een config is required als hij een onderdeel of het hele document breekt. Een config is recommended als het alleen impact heeft op zichzelf.

Test html build

Het is goed om de Node.js packages up-to-date te houden. Maar omdat die packages van 3e partijen zijn is het handig om wel te controleren of het document nog wel naar behoren werkt na een update. Het test-html-build script maakt een snapshot en vergelijkt de html met een stabiele snapshot (respec profiel wordt geladen van gitdocumentatie.logius.nl). Als er dus onverwachte veranderingen zijn kunnen die makkelijk ontdekt worden. De test is te runnen met npm run compare:builds maar de test zit ook in de push GitHub workflow en word dus ook uitgevoerd na een push naar de main branch. Na het uitvoeren van de test zijn de outputs ervan te vinden in action die de test heeft uitgevoerd. Die actions zijn te vinden onder de actions tab op github.

Guides

Document configuration options

Global configuration options

Document URLs
Clone this wiki locally