Filtertool JavaScript client documentatie

De Dienst Publiek en Communicatie (DPC) van het Ministerie van Algemene Zaken ontwikkelt namens de Rijksoverheid een client voor de applicatie ‘Filtertools’.

De client kan gebruikt worden door websites om - zonder zelf te hoeven programmeren - gebruik te maken van de 'Filtertools' API om zo een filtertool op een website te plaatsen.

De client bestaat uit:

  1. Een distributie die gedownload kan worden om op een website te plaatsen

  2. Documentatie voor ontwikkelaars om de client op een website te plaatsen

  3. Een online versie van de client welke opgenomen kan worden in een website.

Hoe te implementeren

Basis

De client bestaat uit 2 bestanden: een JavaScript en een stylesheet. De JavaScript en CSS moet je toevoegen aan de webpagina. Dit kan door hem te downloaden en hem op je eigen site te plaatsen. Bedenk dan wel dat je dan zelf updates moet binnenhalen. Een andere manier is om hem op te nemen via deze website. Dit kun je doen door onderstaande tags toe te voegen aan je pagina. De eerste moet je opnemen in de head-tag. De tweede moet je opnemen in de body-tag op de locatie waar je filtertool wilt tonen. De locatie van de laatste tag is niet zo strict en kan bijvoorbeeld onderaan de body-tag boven de configuratie. De CSS file bevat een minimale styling, je zult voor je eigen site waarschijnlijk nog wat styling willen toevoegen.

<link rel="stylesheet" href="https://www.contenttoolsrijksoverheid.nl/releases/v1-1.19/filtertool-client-v1-1.19.css" type="text/css"/>
<div id="filtertool-container"></div>
<script src="https://www.contenttoolsrijksoverheid.nl/releases/v1-1.19/filtertool-client-v1-1.19.min.js" type="text/javascript"></script>

Als de JavaScript is opgenomen op de webpagina, komt er een variabele genaamd FilterToolClient beschikbaar. Een belangrijke stap om een filtertool op de webpagina te krijgen, is het initialiseren van de client met een configuratie (object). Op de demo pagina is te zien hoe de filter tool eruit kan komen te zien. Ook kun je de client daar configureren en de code kopiëren.

Voorbeeld

Hieronder staan een voorbeeld van hoe je de client kunt initialiseren:

FilterToolClient.init({
    filterToolURL: 'URL naar de gewenste filtertool',
    language: 'nl-NL',
    divElementId: 'filtertool-container',
    showTitle: true,
    showDescription: true
});

Hooks en events

De client genereert voor verschillende acties een event zodat hierop ingehaakt kan worden voor bijvoorbeeld het koppelen met een analytics tool.

Event naamOmschrijving

loadfiltertool-pre

Voordat de client een filtertool inleest

loadfiltertool-post

Nadat de client een filtertool heeft ingelezen

selectanswer

Gebruiker selecteert een antwoord

previousquestion-pre

Voordat een gebruiker naar de vorige vraag navigeert

previousquestion-post

Nadat een gebruiker naar de vorige vraag is genavigeerd

nextquestion-pre

Voordat een gebruiker naar de volgende vraag navigeert

nextquestion-post

Nadat een gebruiker naar de volgende vraag is genavigeerd

finishquestions-pre

Het moment dat een gebruiker op de 'Toon resultaten' knop drukt

finishquestions-post

Nadat een gebruiker op de 'Toon resultaten' knop heeft gedrukt

showresults-pre

Voordat de gebruiker de resultaten te zien krijgt

showresults-post

Nadat de gebruiker de resultaten te zien krijgt

opencontentblock

Het openen van een contentblok

closecontentblock

Het sluiten van een contentblok

openexternallink

Bij het openen van een externe link

openhelp

Bij het openen van de hulp informatie

closehelp

Bij het sluiten van de hulp informatie

changeanswer-pre

Voordat een antwoord wordt gewijzigd

changeanswer-post

Nadat een antwoord is gewijzigd

reset-pre

Voor de reset van het filtertool formulier

reset-post

Na de reset van het filtertool formulier

changegrouping

Bij het wijzigen van groepering

downloadpdf

Bij het downloaden van een pdf

Een eventlistener kan worden toegevoegd aan het filtertool container element. Dit element heeft standaard het id 'filtertool-container' en is eventueel anders indien er in de filtertool client configuratie de 'divElementId' optie is gezet.

Zie hieronder een voorbeeld dat uitgaat van de standaard configuratie.

function addLocalEventListener(element, eventName, handler) {
    if (element.addEventListener) {
        element.addEventListener(eventName, handler);
    } else { // IE voor versie 9
        element.attachEvent('on' + eventName, handler);
    }
}

addLocalEventListener(document.getElementById('filtertool-container'), 'loadfiltertool-post', function(e) { console.log("Filtertool was loaded: ", e)});

Release notes

Versionering

De versie van de client sluit aan op een versie van de API. De opbouw van het versienummer is als volgt: versie van de API gevolgd door een hyphen '-' gevolgd door de versie van de client. Bijvoorbeeld versie "v1-1" betekent versie 1 van de client die aansluit op versie v1 van de API.

Als er een nieuwere versie van de client wordt gepubliceerd die backwards compatibel is, dan wordt deze uitgebracht onder hetzelfde versienummer. Dit kunnen bijvoorbeeld patches zijn met bug fixes of functionaliteit die geen wijzigingen in de interactie teweeg brengen. Als een nieuwere versie van de client niet backwards compatibel is en/of ingrijpende functionaliteit verandert, dan volgt er een nieuwe versienummer van de client. Dit geldt dus alleen voor het gedeelte achter de hyphen '-'. Al deze versies van de client blijven bruikbaar met dezelfde API-versie.

Omdat er dus nieuwe builds (patches) gereleased worden onder hetzelfde versienummer, hebben we in het release-overzicht de bouwdatum vermeld. Als je de client downloadt, dan kun je hiermee controleren of je de laatste versie hebt.

Releases

Hieronder staan de minified en non-minified versies van de client om op te nemen of te downloaden. Heeft u behoefte aan de broncode, neem dan contact op met applicatiespro@minaz.nl.

ReleaseBouwdatum

minified JS v1-1.19
non-minified JS v1-1.19
minified CSS v1-1.19
non-minified CSS v1-1.19

2019-08-12 14:07:35 UTC

minified JS v1-1.18
non-minified JS v1-1.18
minified CSS v1-1.18
non-minified CSS v1-1.18

2019-04-08 14:20:21 UTC

minified JS v1-1.17
non-minified JS v1-1.17
minified CSS v1-1.17
non-minified CSS v1-1.17

2019-02-13 11:27:54 UTC

minified JS v1-1.16
non-minified JS v1-1.16
minified CSS v1-1.16
non-minified CSS v1-1.16

2019-02-06 11:00:33 UTC

minified JS v1-1.15
non-minified JS v1-1.15
minified CSS v1-1.15
non-minified CSS v1-1.15

2018-12-12 09:46:40 UTC

minified JS v1-1.14
non-minified JS v1-1.14
minified CSS v1-1.14
non-minified CSS v1-1.14

2018-11-21 13:01:21 UTC

minified JS v1-1.13
non-minified JS v1-1.13
minified CSS v1-1.13
non-minified CSS v1-1.13

2018-10-16 14:35:40 UTC

minified JS v1-1.12
non-minified JS v1-1.12
minified CSS v1-1.12
non-minified CSS v1-1.12

2018-08-23 12:56:53 UTC

minified JS v1-1.11
non-minified JS v1-1.11
minified CSS v1-1.11
non-minified CSS v1-1.11

2018-07-18 11:50:01 UTC

minified JS v1-1.10
non-minified JS v1-1.10
minified CSS v1-1.10
non-minified CSS v1-1.10

2018-07-10 08:34:04 UTC

minified JS v1-1.9
non-minified JS v1-1.9
minified CSS v1-1.9
non-minified CSS v1-1.9

2018-06-12 13:05:30 UTC

minified JS v1-1.8
non-minified JS v1-1.8
minified CSS v1-1.8
non-minified CSS v1-1.8

2018-05-15 11:29:58 UTC

minified JS v1-1.7
non-minified JS v1-1.7
minified CSS v1-1.7
non-minified CSS v1-1.7

2018-05-08 09:05:56 UTC

minified JS v1-1.6
non-minified JS v1-1.6
minified CSS v1-1.6
non-minified CSS v1-1.6

2018-03-27 11:15:28 UTC

minified JS v1-1.5
non-minified JS v1-1.5
minified CSS v1-1.5
non-minified CSS v1-1.5

2018-03-06 14:38:08 UTC

minified JS v1-1.4
non-minified JS v1-1.4
minified CSS v1-1.4
non-minified CSS v1-1.4

2018-02-27 14:46:38 UTC

minified JS v1-1.3
non-minified JS v1-1.3
minified CSS v1-1.3
non-minified CSS v1-1.3

2018-01-24 11:51:44 UTC

minified JS v1-1.2
non-minified JS v1-1.2
minified CSS v1-1.2
non-minified CSS v1-1.2

2017-12-20 15:27:10 UTC

minified JS v1-1.1
non-minified JS v1-1.1
minified CSS v1-1.1
non-minified CSS v1-1.1

2017-12-06 10:00:40 UTC

minified JS v1-1
non-minified JS v1-1
minified CSS v1-1
non-minified CSS v1-1

2017-11-27 13:32:37 UTC

Changelog

Meer uitleg over specifieke configuratievelden is hierboven te vinden.

Versie v1-1.19

  • Bug met extra quote in element-ID bij helpteksten opgelost.

  • aria-controls-attributen omgezet naar aria-describedby.

  • Alleen bij de alles-in-eenweergave van de filtertool (questionsDisplayType === 'ALL_AT_ONCE') wordt er nog naar de bovenkant van de filtertool gescrolld bij het tonen van het resultaat of het opnieuw invullen.

  • Bugfix om altijd 'Tot slot' in de voortgangsindicator te tonen bij de laatste vraag. Hiermee is de voortgangsindicator consistent met het tonen van de knop 'Toon resultaat'.

  • De babel-polyfill-library wordt niet langer gebruikt. Hierdoor heeft de client minder afhankelijkheden en een kleinere bestandsgrootte.

Versie v1-1.18

  • De client ondersteunt nu een filtertool met questionsDisplayType === 'ALL_AT_ONCE'. Hierbij worden alle vragen tegelijk getoond, vergelijkbaar met een ouderwets HTML-formulier. Bij het wijzigen van een antwoord worden de antwoorden van irrelevante vragen verwijderd en worden irrelevante vragen daarna disabled. Als dit veld ontbreekt of een onbekende waarde heeft, wordt de standaard 'ONE_BY_ONE' gebruikt. Hierbij worden de vragen één voor één getoond.

  • Het verbergen van elementen gebeurt nu middels één generieke class filtertool-element-hidden. Specifieke styling voor bepaalde elementen kan nog steeds gedaan worden, maar nu middels een combinatie van classes. De classes filtertool-question-hidden, filtertool-question-visible, filtertool-questions-form-hidden, filtertool-button-hidden, filtertool-location-section-hidden, filtertool-location-hidden, filtertool-feedback-section-hidden en filtertool-contentblocks-section-hidden worden niet meer gebruikt.

  • De client biedt ondersteuning aan een nieuw vraagtype TOGGLE. Deze kan gestyled worden middels de classes beginnend met .radio-switch om het op een schakelvraag (toggle) te laten lijken.

Versie v1-1.17

  • De teksten van contentblokken kunnen nu naast koppen ook subkoppen bevatten. Deze worden respectievelijk naar H4 & H5 danwel H5 & H6 vertaald, afhankelijk van de bovenliggende koppen.

  • Het label 'Nog 1 vraag' is vervangen door 'Tot slot' (ook in de andere mogelijke talen).

Versie v1-1.16

  • Door het gebruik van de eigenschap "Contentblokken open tonen" in een filtertool is het mogelijk om per filtertool in te stellen bij hoeveel contentblokken in het uiteindelijke resultaat de contentblokken uitgeklapt getoond moeten worden.

  • De client geeft nu de volledige URL door bij het opslaan van een PDF, zodat deze in de PDF getoond kan worden.

Versie v1-1.15

  • Bugfix om environmentURL-configuratieparameter uit de client te halen.

Versie v1-1.14

  • De client biedt nu ondersteuning voor het invullen van een locatievraag. Nadat een gebruiker de locatievraag heeft ingevuld worden de relevante contentblokken verrijkt met extra informatie van de desbetreffende gemeente.

  • Er zijn nieuwe generieke CSS classes voor de helpteksten: filtertool-help, filtertool-help-text-button en filtertool-help-text. Deze vervangen respectievelijk filtertool-question-help, filtertool-question-help-text-button en filtertool-question-help-text.

Versie v1-1.13

  • Technische release om de Content Security Policy voor deze site mogelijk te maken.

Versie v1-1.12

  • Indien contentblokken gesorteerd zijn voor een bepaalde groep, zal deze sortering getoond worden. Anders wordt standaard gesorteerd op de titel van een contentblok.

Versie v1-1.11

  • Doordat de titel van een filtertool via configuratie wel of niet te tonen is werkte de 'Naar boven' knop onderaan de filtertool niet in alle gevallen. Hij linkt nu naar het kader waar deze titel zich onder andere (normaliter) in bevindt.

  • De "Of wijzig uw antwoorden" knop linkt niet meer naar de titel van de terugkoppeling, omdat die afwezig kan zijn. Hij linkt nu naar het kader waar deze titel zich onder andere in kan bevinden.

Versie v1-1.10

  • Hook events toegevoegd. De client stuurt nu bij acties van de gebruiker events die kunnen worden afgevangen op het root element.

  • De buttons voor het open- en dichtklappen van de helpteksten en contentblokken bevatten nu standaard de aria-label als tekst (met font-size: 0 dus niet zichtbaar) om oude screenreaders te ondersteunen die geen aria-labels kunnen lezen.

  • De indicator wordt niet meer getoond als de laatste vraag gewijzigd wordt.

  • Omdraaien van blokken resultaten en terugkoppeling in zowel client als pdf.

  • Mogelijkheid om een resultaat bodytekst toe te voegen.

Versie v1-1.9

  • Taalsets voor alle labels voor fr-FR (Frans) en es-ES (Spaans) zijn toegevoegd.

  • Bugfix om de contentblokken uitgeklapt te tonen in IE11 bij printen. In de CSS media print werd display: initial gebruikt en nu display: block.

Versie v1-1.8

  • Diverse verbeteringen in de (basis) CSS. Voorheen zat er opmaak in onze opgemaakte CSS die eigenlijk in de basis CSS hoort. De opgemaakte CSS is bedoeld alleen voor deze website.

Versie v1-1.7

  • De client toont een voortgangsindicator met het maximum aantal nog te beantwoorden vragen. De configuratieoptie answeringQuestionsIsMandatory komt hiermee te vervallen. Er kan eventueel styling toegevoegd worden om de voortgangsindicator anders op te maken.

  • Headerniveaus zijn nu beter ingedeeld. De bodyText van contentblokken zullen voortaan hoogstens een h1 bevatten. De client zal deze omzetten naar een h3 of h4 afhankelijk van of er groepen zijn.

Versie v1-1.6

  • Getoonde contentblokken kunnen als PDF worden opgeslagen. Hiervoor is er geen extra configuratie of styling nodig. Eventueel kan de knop om de PDF te downloaden anders opgemaakt worden.

  • Indien een geselecteerde antwoordoptie geen terugkoppeling heeft, wordt nu ook de vraag getoond naast de geselecteerde antwoordoptie in de terugkoppeling.

  • Bugfix om geselecteerde antwoorden te verwijderen als een vraag irrelevant wordt bij het navigeren met de knop "Vorige vraag".

  • Verander de volgorde van de knoppen voor de vorige en volgende vraag en het resultaat in de DOM voor toegankelijkheid. In de gebruikersinterface wordt deze wel gelijk gehouden door een float aan de CSS toe voegen voor de knoppen.

Versie v1-1.5

  • De client bevat een print stylesheet. Hiermee kan het resultaat van de filtertool geprint worden, waarbij alle getoonde contentblokken opengeklapt en alle knoppen weggelaten worden.

Versie v1-1.4

  • De client ondersteunt de Nederlandse en Brits-Engelse taal in de interface. Hiervoor komt er een optionele configuratieoptie language bij. Deze staat standaard op Nederlands. Zodra de filtertool succesvol is opgehaald, wordt het veld language van de filtertool gebruikt. Voorheen kon voor bepaalde meldingen HTML geïnjecteerd worden. Deze configuratieopties zijn nu hernoemd van *Template naar *Text en verwachten nu platte tekst. Door de optionele configuratieopties te gebruiken worden de ingebakken teksten van de desbetreffende taal overschreven.

  • Bugfix om het resultaat te tonen ook als er een invalide link in een contentblok voorkomt. Deze bug komt alleen in IE11 en Edge voor.

  • De client behoudt gegeven antwoorden bij het wijzigen van een vraag via de Wijzig-knop. Hiervoor is er geen extra configuratie of styling nodig.

Versie v1-1.3

  • De kopteksten boven de terugkoppeling en het resultaat worden voortaan uit de API gehaald. Hiermee komen de optionele configuratievelden feedbackHeader en resultHeader te vervallen. Hiervoor is er geen extra styling nodig.

  • Als een gekozen antwoordoptie geen terugkoppeling heeft uit de API, dan wordt de gekozen antwoordoptie zelf getoond als terugkoppeling. Hiervoor is er geen extra configuratie of styling nodig.

Versie v1-1.2

  • Groepen van contentblokken worden in het resultaat op volgorde weergegeven. Deze volgorde is niet meer alfabetisch, maar gebaseerd op de volgorde die de huidige versie van de API ontsluit. Hiervoor is er geen extra configuratie of styling nodig.

Versie v1-1.1

  • Met behulp van het optionele configuratieveld linkOpensInNewTabText kan er een standaard tekst achter elke link worden gezet. Daarnaast krijgen alle links die naar een extern domein verwijzen, het attribuut class="filtertool-external-link". Hiermee kunnen externe links desgewenst anders worden opgemaakt, bijvoorbeeld met een icoon achter de link. Alle links hebben target=_blank als attribuut.

Versie v1-1.0

Eerste oplevering.