# Web App Startpunt

- **Versie**: 1.2.0
- **Meest recente update**: 07-01-2026

Welkom bij het _Web App Startpunt_, een major update van wat voorheen de _DPC Interactieve Infographic Sandbox_ heette. De sandbox-insteek is losgelaten en vervangen door een 'starter project' met daarin verschillende (stijl)elementen en features die het de maker gemakkelijker zou moeten maken om een web app te bouwen die naadloos aansluit op de site waarop die uiteindelijk geplaatst wordt.

## Vereisten

De meeste elementen van dit startpunt zijn slechts suggesties, maar een aantal dingen zijn vereist voor het bouwen en correct aanleveren van een **web app** voor het PRO-platform:

- De web app moet gebouwd zijn in [React](https://reactjs.org/).
- De web app moet werken in / gebruikmaken van de [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
- De web app moet voldoen aan de eisen voor [toegankelijkheid](https://www.digitoegankelijk.nl/uitleg-van-eisen).
- De web app mag geen gebruikmaken van het Rijksoverheid iconenfont.
- De web app moet werken in de pro-preview-tool.

- Afhankelijkheden hebben geen bekende kwetsbaarheden. Dit controleer je met het commando `pnpm audit`. De verantwoordelijkheid van het bijhouden van afhankelijkheden en het voorkomen van kwetsbaarheden daarin, voor en na de plaatsing, ligt en blijft bij de indiener van de web app. Het staat DPC vrij om bij kwetsbaarheden de web app offline te halen.

## Werking

### Web App ID

In dit project is er een variabele (`VITE_WEB_APP_ID`) in het `.env` bestand. Verander dit naar een id voor jouw web app. Dit id wordt gebruikt voor 2 dingen:

- Hiermee identificeren we de web app om versies te beheren.
- Dit zorgt ervoor dat de web app in de juiste container geladen wordt. Dit gebeurt op drie plekken: (`index.html`, `src/Main.tsx` en `postcss.config.js`).

### Fonts

Omdat webfonts niet direct in de Shadow DOM ge-embed kunnen worden, is het alleen mogelijk om gebruik te maken van webfonts die al voor de omringende site zijn ingeladen. In dit project zijn de vier fonts die op de verschillende PRO-sites gebruikt worden meegeleverd, maar worden slechts ingezet voor preview-doeleinden. In de output van dit project worden de fonts daarom ook niet meegnomen.

De standaard lettergrootte op het huidige PRO-platform is 10px. Na de migratie is dit de standaard 16px. Hierom is het verstandig om hier rekening mee te houden wanneer er gebruik wordt gemaakt van relatieve lettergroottes. Zet in dat geval bijvoorbeeld de lettergrootte op de web-apps-container class en gebruik vervolgens em.

## Assets

Assets moeten worden toegevoegd door middel van createAssetPath(). De bestandslocatie in development is anders dan op het PRO-platform. Om assets op het platform te laten werken, moet de src-locatie gewrapt worden in createAssetPath().

In de CSS kunnen er dus ook geen absolute paden gebruikt worden in een url-tag. In het startpunt zitten twee voorbeelden waarmee we laten zien hoe je iconen kunt gebruiken.

### Naamgevingsconventies

**Gebruik geen** `_` (underscore) in bestandsnamen. In plaats daarvan, maak gebruik van een `-` koppelteken. De reden hiervoor is dat het CMS underscores vervangt voor koppeltekens waardoor bestanden anders worden gelezen.

## Data sets

Door gebruik te maken van de data-set-attributen kun je data inladen uit bestanden die in het CMS zijn opgeslagen in de map `webapp-data`.

Er zijn maximaal vier data-set-attributen beschikbaar:
`data-set-1`, `data-set-2`, `data-set-3` en `data-set-4`.

Voor development kun je deze data sets aanpassen in
`pro-preview-tool/public/index.html`, zodat je de functionaliteit lokaal kunt testen.

In productie worden deze URL’s automatisch overschreven met de URL’s die verwijzen naar de bestanden in het CMS.

### Voorbeeldstructuur

```
<div
  id="id-van-je-webapp"
  class="web-app-container"
  data-set-1="/binaries/webapp-demo/rocolors.csv"
  data-set-2=""
  data-set-3=""
  data-set-4=""
></div>

```

### Uitlezen van datasets

Gebruik binnen je React-component de hook `useDataSet()` om toegang te krijgen tot de dataset-configuratie:

Voorbeeld in bestand: `src/components/OnlineCommunicationColors.tsx`

```
const { dataSets } = useDataSet();
const dataSet = dataSets?.["set-1"];

```

## Stuurbestand

Een stuurbestand kan worden gebruikt als er meerdere webapps zijn die dezelfde data moeten gebruiken. In het CMS kan je een stuurbestand koppelen aan een webapp. Als dit bestand aangepast wordt in het CMS, dan wijzigt deze data in alle webapps die dit stuurbestand gebruiken.

Voor development kun je deze data set aanpassen in
`pro-preview-tool/public/index.html`, zodat je de functionaliteit lokaal kunt testen.

In productie wordt deze URL automatisch overschreven met de URL die verwijst naar het bestand in het CMS.

### Voorbeeldstructuur

```
<div
  id="id-van-je-webapp"
  class="web-app-container"
  data-control-file="/binaries/webapp-demo/control-file.json"
></div>

```

### Uitlezen van een stuurbestand

Gebruik binnen je React-component de hook `useDataSet()` om toegang te krijgen tot de dataset-configuratie:

Voorbeeld in bestand: `src/components/OnlineCommunicationColorsJson.tsx`

```
const { dataSets } = useDataSet();
const stuurbestand = dataSets?.["controlFile"];

```

## Toegankelijkheid

Houdt met het ontwikkelen van de web app al rekening met het feit dat de web app toegankelijk moet zijn volgens de specificaties van de [WCAG](https://www.w3.org/TR/WCAG21/). Enkele aandachtspunten zijn:

- **Kleurcontrast**: Er zijn eisen voor het contrast van tekst op een kleurvlak. Dit is onder andere te controleren met de [APCA contrastchecker](https://contrast.tools/).
- **Leesbare tekst**: Houdt rekening met bezoekers die vertrouwen op screenreaders. Dit houdt in dat teksten in afbeeldingen niet toegankelijk zijn. Het toevoegen van een ALT-tekst is niet altijd voldoende.
- **Bediening**: Veel bezoekers en assistive hulpmiddelen vertrouwen op navigatie met een toetsenbord. Zorg ervoor dat alle klikbare elementen ook te bedienen zijn met een toetsenbord. Dit houdt in dat je geen niet-klikbare elementen moet gebruiken en deze vervolgens met JavaScript wel klikbaar te maken.
- **Dynamische content**: Zodra inhoud van de web app dynamisch wisselt (popup, sliders etc.) is dit niet voor alle gebruikers waarneembaar. Je zult met JavaScript en [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA)-tags moeten zorgen dat ook gebruikers met bijvoorbeeld screenreaders of braillelezers op de hoogte gebracht worden van de nieuwe informatie op de pagina.
- Zorg ook voor een **leesbaar alternatief** voor iconen en buttons met pijlen of kruisjes.
- Meer informatie is te vinden op [digitoegankelijk.nl](https://www.digitoegankelijk.nl) en [w3.org](https://www.w3.org/TR/WCAG21/).

## PRO-preview-tool

Omdat we geen toegang kunnen verlenen tot de omgeving waar de web app uiteindelijk wordt ingeladen, hebben we geprobeerd een representatieve preview tool te maken. Deze is te vinden in de map pro-preview-tool. Gebruik deze tool voordat je de web app opstuurt.

De tool werkt als volgt:

- Installeer de dependencies met pnpm install.
- Start de preview met pnpm preview.

De preview tool controleert ../dist op veranderingen. Als er wijzigingen zijn, worden de bestanden gekopieerd en weergegeven in de preview.

We hebben geprobeerd de tool te laten overeenkomen met de PRO-websites. Als alle criteria uit deze readme gevolgd worden, zou de web app correct weergegeven moeten worden in de preview tool. Het is mogelijk dat er tijdens het reviewproces nog steeds problemen naar voren komen. We proberen deze onderliggende eisen dan op te nemen in de preview tool zodat deze in de toekomst eerder opgemerkt kunnen worden.

De PRO-preview-tool werkt op dit moment voor websites die nog niet gemigreerd zijn naar het nieuwe PRO-platform. Zodra de previewtool ook voor gemigreerde websites beschikbaar is, delen we dit in het startpunt.

## Kwaliteit

Om de kans op issues later in het proces te verkleinen, is het aan te raden om met degelijke controle tools te werken:

### Visual Studio Code + extensies

- [VS Code](https://code.visualstudio.com/) code editor
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extensie
- [webhint](https://marketplace.visualstudio.com/items?itemName=webhint.vscode-webhint) extensie
- [axe Accessibility Linter](https://marketplace.visualstudio.com/items?itemName=deque-systems.vscode-axe-linter) extensie
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extensie
