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:
Een distributie die gedownload kan worden om op een website te plaatsen
Documentatie voor ontwikkelaars om de client op een website te plaatsen
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.24/filtertool-client-v1-1.24.css" type="text/css"/>
<div id="filtertool-container"></div>
<script src="https://www.contenttoolsrijksoverheid.nl/releases/v1-1.24/filtertool-client-v1-1.24.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 naam | Omschrijving |
|---|---|
loadfiltertool-pre | Voordat de client een filtertool inleest |
loadfiltertool-post | Nadat de client een filtertool heeft ingelezen |
save-questions-state-pre | Voor het opslaan van de staat van geselecteerde antwoorden |
save-questions-state-post | Na het opslaan van de staat van geselecteerde antwoorden |
save-questions-state-error | Indien het opslaan van de staat van geselecteerde antwoorden niet lukt |
load-questions-state-pre | Voor het laden van de staat van geselecteerde antwoorden |
load-questions-state-post | Na het laden van de staat van geselecteerde antwoorden |
load-questions-state-error | Indien het laden van de staat van geselecteerde antwoorden niet lukt |
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 |
opengroup | De gebruiker opent een groep in de compacte weergave |
closegroup | De gebruiker sluit een groep in de compacte weergave |
opencontentblock | Het openen van een contentblok |
closecontentblock | Het sluiten van een contentblok |
save-contentblocks-state-pre | Voor het opslaan van de staat van de weergave van contentblokken |
save-contentblocks-state-post | Na het opslaan van de staat van de weergave van contentblokken |
save-contentblocks-state-error | Indien het opslaan van de staat van de weergave van contentblokken niet lukt |
load-contentblocks-state-pre | Voor het laden van de staat van de weergave van contentblokken |
load-contentblocks-state-post | Na het laden van de staat van de weergave van contentblokken |
load-contentblocks-state-error | Indien het laden van de staat van de weergave van contentblokken niet lukt |
save-location-state-pre | Voor het opslaan van de staat van de locatie |
save-location-state-post | Na het opslaan van de staat van de locatie |
save-location-state-error | Indien het opslaan van de staat van de locatie niet lukt |
load-location-state-pre | Voor het laden van de staat van de locatie |
load-location-state-post | Na het laden van de staat van de locatie |
load-location-state-error | Indien het laden van de staat van de locatie niet lukt |
openexternallink | Bij het openen van een externe link |
openlocationlink | Bij het openen van een link in de locatiegebaseerde content |
openhelp | Bij het openen van de hulpinformatie |
closehelp | Bij het sluiten van de hulpinformatie |
changeanswer-pre | Voordat een antwoord wordt gewijzigd |
changeanswer-post | Nadat een antwoord is gewijzigd |
reset-pre | Voor de reset van het filtertoolformulier |
reset-post | Na de reset van het filtertoolformulier |
changegrouping | Bij het wijzigen van groepering |
downloadpdf | Bij het downloaden van een pdf |
setlocation | Bij het instellen van de locatie voor locatiegebaseerde content |
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 applicatiebeheer@beheerrijksoverheid.nl.
Changelog
Meer uitleg over specifieke configuratievelden is hierboven te vinden.
Versie v1-1.20
Er is functionaliteit toegevoegd om ingevoerde gegevens op te slaan in de
sessionStorage. Deze functionaliteit is altijd ingeschakeld. Hierdoor is het mogelijk om binnen hetzelfde tabblad te navigeren naar een andere locatie en terug. De filtertool wordt hierbij weer in dezelfde toestand ingeladen. Er zijn hooks toegevoegd voor het opslaan en laden van de staat van geselecteerde antwoorden, groeperingen en locatie.Er is functionaliteit toegevoegd voor het compact tonen van het resultaat. De filtertool heeft nu een nieuw veld erbij,
resultDisplayType. Als de waarde hiervanFULLis, blijft de client werken zoals voorheen. Als de waarde hiervanCOMPACTis, dan wordt de compacte weergave gebruikt, deze werkt als volgt: De groepen van het resultaat zijn dan inklapbaar en standaard ingeklapt. Er kan hoogstens één groep opengeklapt zijn. Binnen deze opengeklapte groep kan er hoogstens één contentblok opengeklapt zijn. Als een ander contentblok opengeklapt wordt, dan sluit de vorige. Als een andere groep opengeklapt wordt, dan sluit de vorige groep en eventueel opengeklapte contentblokken.
Er zijn twee hooks toegevoegd:opengroupenclosegroup. Deze worden geactiveerd als de gebruiker een groep openklapt en dichtklapt, respectievelijk. Er is een classfiltertool-contentblocks-group-toggle-buttonbijgekomen voor de knop.
Lege groepen worden niet meer aan het DOM toegevoegd. Het verbergen gebeurt niet langer meer middels styling. Daardoor is ook de styling vanfiltertool-contentblocks-group-headerveranderd.
De vier sleutels uit de taalsets voor de knoppen voor het open- en dichtklappen van contentblokken zijn veranderd. Dit was bijvoorbeeldshowContentBlocksButtonTexten is nu enkelvoudshowContentBlockButtonText. Er zijn vier sleutel-waardeparen toegevoegd aan de taalsets voor de knoppen voor het open- en dichtklappen van groepen. Deze hebben als sleutelshowGroupButtonText,showGroupButtonAriaLabel,hideGroupButtonTextenhideGroupButtonAriaLabel. De waardes zijn hetzelfde als voor de contentblokken.
Alle verborgen elementen worden nu met de print stylesheet getoond. Hierdoor worden ook gesloten groepen getoond.
Alle filtertools maken geen gebruik meer van het veldresultHeader. Deze krijgt voortaan altijd de waardenullvan de API. Alle oude clients tonen al geen resultaatkop als dit veld leeg is, dus dit is backwards compatible. De classfiltertool-contentblocks-header-textis hiermee ook komen te vervallen.
De link voor het wijzigen van antwoorden is verwijderd uit de client. Evenzo isorChangeYourAnswersuit de taalsets verwijderd.
Er wordt voortaan vanclassListin plaats vanclassNamegebruik gemaakt.De client biedt ondersteuning aan een nieuw vraagtype
SINGLE_SELECT_DROPDOWN. Hierbij worden de antwoordopties in eenselect-element weergegeven. Deze kan gestyled worden door middel van de classfiltertool-question-dropdown.Bug opgelost waarbij de knop 'Toon resultaat' soms
disabledwas. Dit trad op bij een filtertool met alles-in-eenweergave (questionsDisplayType === 'ALL_AT_ONCE') met schakelvragen met bepaalde onderlinge afhankelijkheden.Bug opgelost waarbij relevante vraag-antwoordcombinaties op basis van een
SINGLE_SELECT_DROPDOWN-vraag niet goed werden afgehandeld.
Versie v1-1.19
Bug met extra quote in element-ID bij helpteksten opgelost.
aria-controls-attributen omgezet naararia-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 daarnadisabled. 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 classesfiltertool-question-hidden,filtertool-question-visible,filtertool-questions-form-hidden,filtertool-button-hidden,filtertool-location-section-hidden,filtertool-location-hidden,filtertool-feedback-section-hiddenenfiltertool-contentblocks-section-hiddenworden niet meer gebruikt.De client biedt ondersteuning aan een nieuw vraagtype
TOGGLE. Deze kan gestyled worden middels de classes beginnend met.radio-switchom 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.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 (locatiegebaseerde content).
Er zijn nieuwe generieke CSS classes voor de helpteksten:
filtertool-help,filtertool-help-text-buttonenfiltertool-help-text. Deze vervangen respectievelijkfiltertool-question-help,filtertool-question-help-text-buttonenfiltertool-question-help-text.
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) enes-ES(Spaans) zijn toegevoegd.Bugfix om de contentblokken uitgeklapt te tonen in IE11 bij printen. In de CSS media print werd
display: initialgebruikt en nudisplay: 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
answeringQuestionsIsMandatorykomt hiermee te vervallen. Er kan eventueel styling toegevoegd worden om de voortgangsindicator anders op te maken.Headerniveaus zijn nu beter ingedeeld. De
bodyTextvan contentblokken zullen voortaan hoogstens eenh1bevatten. De client zal deze omzetten naar eenh3ofh4afhankelijk 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 het DOM voor toegankelijkheid. In de gebruikersinterface wordt deze wel gelijk gehouden door een
floataan 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
languagebij. Deze staat standaard op Nederlands. Zodra de filtertool succesvol is opgehaald, wordt het veldlanguagevan de filtertool gebruikt. Voorheen kon voor bepaalde meldingen HTML geïnjecteerd worden. Deze configuratieopties zijn nu hernoemd van*Templatenaar*Texten 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
feedbackHeaderenresultHeaderte 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
linkOpensInNewTabTextkan er een standaard tekst achter elke link worden gezet. Daarnaast krijgen alle links die naar een extern domein verwijzen, het attribuutclass="filtertool-external-link". Hiermee kunnen externe links desgewenst anders worden opgemaakt, bijvoorbeeld met een icoon achter de link. Alle links hebbentarget=_blankals attribuut.