Welkom bij de Platform Rijksoverheid sandbox omgeving

Deze documentatie is opgesteld als handleiding voor het maken van interactieve infographics voor het Platform Rijksoverheid Online. Er is een specifieke aanpak en structuur nodig voor het ontwikkelen en aanleveren van interactieve infographics voor dit platform. Naast documentatie vind je in deze Sandbox ook een aantal voorbeelden met meer informatie over de te gebruiken technieken.

Sandbox - Infographics Platform Rijksoverheid

Versie 3.0.0 Laatst geupdate op 21-09-2022

Handleiding Sandbox

De vormgeving en structuur van de sandbox betreft een statische versie van het Platform Rijksoverheid. Dit is gedaan om een goed beeld te geven van de weergave van de uiteindelijke infographic. Het geeft inzicht in de standaard styling en gedrag van diverse elementen, welke ook effect hebben op de elementen en scripts van een infographic.

In deze Sandbox vind je een aantal mappen. Wij leggen ze even uit.

.
├── behaviour           # JavaScripts voor het Platform Rijksoverheid
├── presentation        # Styling voor het Platform Rijksoverheid
├── docs                # Documentatie over de Sandbox
├── examples            # Voorbeeld Interactieve Infographics voor de Sandbox
├── mijn-infographic    # Root map voor Infographic ontwikkeling
├── node_modules        # NPM packages voor de Sandbox (Alleen na installatie)
├── gulpfile.js         # Configuratiebestand voor Gulp-taken
├── package.json        # Configuratie van het npm project
└── index.html          # Homepagina van de Sandbox

Er is in de sandbox standaard een Browsersync Server meegeleverd om het inladen van bestanden zo reëel mogelijk te laten verlopen en problemen bij het aanleveren te voorkomen. De Browsersync Server is geconfigureerd middels Gulp. Om de sandbox als een basis ontwikkelomgeving te gebruiken is er een aantal Gulp taken beschikbaar om SASS te compilen en Javascript / CSS te minifien.

Om de omgeving te installeren dien je Node.js (nodejs.org) te installeren. Daarna open je de root folder van de Sandbox in terminal of een andere command line interface. Hierna gebruik je het commando npm install om de nodige plugins en tools te installeren.

Na de installatie van de plugins gebruik je het commando npm start om de server en taken te starten. De terminal zal een bevestiging geven wanneer de server draait, iets dat lijkt op:

Using gulpfile ~/Desktop/sandbox/gulpfile.js
Starting 'develop'...
Starting 'startServer'...
Webserver started at http://localhost:8080
Finished 'startServer' after 13 ms
Starting 'startWatchers'...
Finished 'startWatchers' after 12 ms
Finished 'develop' after 27 ms

Navigeer in je browser naar http://localhost:8080 of ga naar http://x.x.x.x:8080 op je mobiel/tablet of een ander extern apparaat om de Sandbox omgeving te bekijken.

Infographic Ontwikkelen

Voor het ontwikkelen van een interactieve infographic vind je in de map mijn-infographics een basis opzet met bestanden. De basisstructuur is als volgt:

.
└── mijn-infographic
    ├── mijn-infographic.html
    ├── style.scss
    ├── style.css
    └── script.js

Naamgeving

De infographic zal in een pagina op het platform geïnjecteerd worden. Hierdoor zijn er wat basis regels waardoor de code van een infographic de code van de website niet beïnvloed. Dit begint bij het maken van een unieke ID voor je infographic. De ID moet samengesteld zijn uit de beginletters van alle woorden van een naam voor je infographic. In de voorbeelden hebben we de infographic Mijn interactieve infographic genomen en is de ID dus mii. Pas deze overal aan met een unieke ID voor jouw infographic.

HTML

  • Open mijn-infographic.html in een script editor Zoek in het bestand naar <code>Hier kun je de code van je infographic plaatsen.</code> Schrijf hier al de benodigde HTML voor je Infographic.
  • Zorg ervoor dat om al je code een wrapper met de ID van je infographic zit bijvoorbeeld <div id="mii"> </div>
  • Zorg ervoor dat je de juiste elementen en een correct semantische HTML opbouw gebruikt. Houdt er rekening mee dat de infographic als een element op een pagina geplaatst wordt. Zo is de H1 van een pagina altijd al gevuld en zul je de semantiek van je HTML hier op aan moeten passen.
  • Valideer regelmatig je HTML op https://validator.w3.org/.
  • Probeer de HTML zo compact mogelijk te houden. Veel data kan bijvoorbeeld beter asyncroon ingeladen worden.

CSS

Om conflicten tussen de CSS van het Platform Rijksoverheid en de infographic te voorkomen moet alle styling alleen op elementen van de infographic toegepast worden. Dit kan onder andere door een unieke prefix van de selectors of door middel van SASS nesting.

Selectors prefixen doe je door op al je elementen een class met een prefix toe te voegen. Dit kan de id van je infographic zijn gevolgd door een underscore. Heeft de infographic bijvoorbeeld de naam ‘Mijn interactive infographic’ dan wordt je prefix ‘mii_’ Je CSS komt er dan bijvoorbeeld zo uit te zien.

.mii_back_link {
    padding: 0 0 0 15px;
    margin: 0 0 0 0l
    color: #999999;
}

.mii_panel_background {
    background: #e1e1e1;
    color: #000000;
}

Door SASS te gebruiken om je CSS te genereren kun je dit makkelijker doen. Zolang je al je classes en ID’s nest binnen de ID van je infographic weet je zeker dat de juiste elementen beïnvloed worden. Je SASS kan dan zo opgebouwd zijn:

#mii {
    .back-link{
        padding: 0 0 0 15px;
        margin: 0 0 0 0l
        color: #999999;
    }
    .panel_background {
        background: #e1e1e1;
        color: #000000;
    }
}

SASS genereerd dan een CSS bestand met de volgende output:

#mii .back-link{
    padding: 0 0 0 15px;
    margin: 0 0 0 0l
    color: #999999;
}
#mii .panel_background {
    background: #e1e1e1;
    color: #000000;
}

In de sandbox is standaard een SASS compiler meegeleverd. Als je in de mijn-infographic folder alleen het SASS bestand gebruikt terwijl de sandbox server actief is zal de css gegenereerd worden zodra je het SASS bestand opslaat.

Controleer regelmatig of je CSS valide is op https://jigsaw.w3.org/css-validator/.

JS

De JavaScripts worden asynchroon geladen. Daarom worden idealiter meerdere javascript bestanden geconcat tot 1 bestand. Het liefst zien we de functies opgebouwd als jQuery plugins (https://learn.jquery.com/plugins/) of als een jQuery widget. De nodige widget factory is aanwezig. Houdt er met het schrijven van functies en plugins rekening mee dat er meerdere instanties op dezelfde pagina aanwezig kunnen zijn. Wees bewust van public en private functies.

JS Libraries

Het is mogelijk diversen Javascript frameworks en libraries te gebruiken. De aanwezige frameworks en libraries zijn:

  • jQuery (v3.6.0)
  • jQuery UI (v1.13.1) Onderdelen: Widget, position, keycode, unique-id, autocomplete, datepicker, menu
  • MediaElementJS (v5.0.5)
  • Leaflet JS (v1.8.0)
  • Highcharts v10)
  • Highmaps (v10)

jQuery en jQuery UI zijn altijd aanwezig en geladen. De andere frameworks en libraries moeten met RequireJS ingeladen worden. Dit werkt als volgt:

MediaElementJS (Video / Audio player)

require(['audiovideo'], function() {
    Hier kun je je eigen code voor MediaElementJS uitvoeren.
});

Leaflet JS (Kaarten)

require(['leaflet'], function() {
    Hier kun je je eigen code voor LeafletJS uitvoeren.
});

Highcharts (Grafieken)

require(['highchart'], function() {
    Hier kun je je eigen code voor Highcharts uitvoeren.
});

Highmaps (Thematische kaarten)

require(['highmaps'], function() {
    Hier kun je je eigen code voor Highmaps uitvoeren.
});

Overige bestanden

Wanneer je eventuele overige bestanden zoals illustraties en afbeeldingen nodig hebt, dan is het van belang deze te plaatsen in de root infographic folder zonder subfolders. Dit is dezelfde folder als waar het html bestand in staat. Een voorbeeld folder-structuur bij gebruik van assets kan er zo uitzien:

.
└── mijn-infographic
    ├── icons.svg
    ├── afbeelding.jpg
    ├── achtergrond.jpg
    ├── style.css
    ├── script.js
    └── mijn-infographic.html

Laden en paden van bestanden

Aangezien een infographic als contentblok op een pagina geladen gaat worden op het Platform is het belangrijk dat alle paden makkelijk en snel aan te passen zijn. Mocht je dus zelf met javascript of css bestanden inladen zorg er dan voor dat er in de readme duidelijk vermeld staat waar welke paden aangepast moeten worden. Hou er ook rekening mee dat de servers van het Platform geen hoofdletters in bestandsnamen en paden ondersteunt. Zorg er dus voor de zowel de bestanden als de verwijzingen geen hoofdletters bevatten.

Toegankelijkheid

Houdt met het ontwikkelen van de infographic al rekening met het feit dat de infographic toegankelijk moet zijn volgens de specificaties van de WCAG. Enkele aandachtspunten zijn:

  • Kleur contrast Er zijn eisen voor het contrast van tekst op een kleurvlak. Dit is onder andere te controleren op https://webaim.org/resources/contrastchecker/.
  • 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 om deze met Javascript wel klikbaar te maken.
  • Dynamische content Zodra inhoud van de infographic dynamisch wisselt (popup, sliders enz) is dit niet voor alle gebruikers waarneembaar. Je zult met Javascript en Aria tags moeten zorgen dat ook gebruikers met bijvoorbeeld screenreaders of braille lezers op de hoogte gebracht worden van de nieuwe informatie op de pagina. Een voorbeeld hiervoor vind je in de popup van de demo infographic.
  • Zorg ook voor een leesbaar alternatief voor iconen en buttons met pijlen of kruisjes Een voorbeeld hiervoor vind je in de popup van de demo infographic.
  • Meer informatie is te vinden op digitoegankelijk.nl en www.w3.org

Aanleveren

Controleer voordat je de infographic aanlevert of je aan alle aanleverspecificaties voldoet en of alle code gevalideerd is. De CSS en Javascript bestanden moeten zowel unminified als minified aangeleverd worden. Als je de Gulp taken uit de sandbox gebruikt hebt voor de ontwikkeling dan zijn er van de CSS en Javascript al minified versies gemaakt in de map min.

Het aangeleverde pakket moet voorzien zijn van een readme bestand waar de globale werking van de infographic in vermeld staat. Alsmede de naam en contactgegevens van de ontwikkelaar en eventueel de locaties in de scripts waar paden naar bestanden aangepast moeten worden.

Daarna kun je alle bestanden uit de mijn-infographic map inpakken in een zip bestand en aanleveren

Voorbeelden

Bekijk de volgende voorbeelden om een indruk te krijgen van de werking van een infographic. Let op! Om de voorbeelden te bekijken moet de Browsersync Server draaien om het inladen van bestanden te laten werken.