Deze pagina is bedoeld voor webbouwers en ontwikkelaars die Tolkie Leeshulp implementeren op een website.
Je leest hier wat er technisch nodig is aan jullie kant, hoe de leeshulp wordt geladen en hoe de integratie samenhangt met de instellingen die de klant in Mijn Tolkie beheert.
Implementatie door Tolkie of door klant zelf?
In de meeste gevallen is de afspraak dat de medewerkers van Tolkie eerst de website van de klant goed bekijken en ervoor zorgen dat de meeste instellingen goed staan. Ze kijken dan naar:
Welke functies van de Tolkie Leeshulp moeten worden ingeschakeld
Welke delen van de pagina wel en niet moeten worden meegenomen in de leeshulp
Welke kleur de Tolkie-knoppen moeten krijgen
Of de css-regels van Tolkie botsen met die van de website
Of alle functies goed werken
Hieronder lees je wat er verder nog moet gebeuren om de leeshulp toe te voegen aan de website.
Let op: Als de implementatie helemaal door de klant of de webbouwer wordt gedaan, dan heb je wat meer tijd nodig voor het instellen en testen van de instellingen. Wat je er moet gebeuren, leggen we uit in dit stappenplan dat we standaard naar klanten sturen die de implementatie zelf doen.
Globaal overzicht
Tolkie Leeshulp wordt toegevoegd via een JavaScript-script dat op de website wordt geladen. Dat script zorgt ervoor dat de leeshulp-functies beschikbaar worden op de pagina.
Welke functies actief zijn (zoals Lees voor, Uitleg woorden of Simpele tekst) wordt afgesproken in de overeenkomst met Tolkie. De webbouwer hoeft deze functies dus niet zelf te activeren of uit te schakelen.
Technisch gezien bestaat de implementatie uit de volgende onderdelen:
Het Tolkie-script toevoegen aan de website
Het opgeven van de leeshulp-variant door middel van een attribuut
De leeshulp-knoppen correct laten verschijnen in de pagina-layout
Zorgen dat de leeshulp opnieuw initialiseert bij dynamische navigatie (in het geval van een SPA)
Rekening houden met de Content Security Policy (CSP)
Eventueel de styling van de knoppen aanpassen met css
1. Het script toevoegen
Tolkie Leeshulp wordt geladen via één <script>-tag.
Deze moet op alle pagina’s staan waar de leeshulp beschikbaar moet zijn.
Een basisvoorbeeld:
<script
id="tolkie-script"
type="module"
src="https://app.tolkie.nl"
crossorigin="anonymous"
data-tolkie-token="<jouw token>"
data-tolkie-state="separateButtons"
defer="">
</script>
In de praktijk plaats je dit script meestal:
in de globale template (header/layout);
in een cms-template die op alle pagina’s wordt gebruikt;
of in een framework-component dat altijd wordt gerenderd.
2. Weergave van de leeshulp (data-tolkie-state)
Met het attribuut data-tolkie-state wordt bepaald hoe de leeshulp op de pagina verschijnt. Deze keuze wordt gemaakt in overleg met de klant.
Als webbouwer hoef je alleen te zorgen dat het juiste attribuut in het script staat.
Standaard en voorkeursvariant: losse knoppen
data-tolkie-state="separateButtons"
Dit is de variant die Tolkie sterk aanbeveelt:
elke functie heeft een eigen knop;
knoppen staan op een vaste plek in de pagina;
bij scrollen verschijnt automatisch een zwevende knop;
dit is de meest toegankelijke variant voor eindgebruikers.
Andere varianten (indien afgesproken)
Één leeshulp-knop:
singleButtonAlleen zwevende knop:
floatingButton
Voor de implementatie maakt dit technisch geen verschil.
3. Waar komen de knoppen op de pagina?
Script op een specifieke plek
De knoppen verschijnen standaard op de plek waar het script in de html staat.
Dit is vaak voldoende bij maatwerk html.
Ankerpunten gebruiken (aanbevolen bij templates)
Als het script in de <head> staat of in een globale template wordt geladen, kun je via classes bepalen waar de knoppen komen:
<div class="tolkie-buttons-afterbegin">
<!-- Hier komen de Tolkie-knoppen -->
</div>
Beschikbare classes:
tolkie-buttons-beforebegintolkie-buttons-afterbegintolkie-buttons-beforeendtolkie-buttons-afterend
Zo blijft de implementatie robuust, ook als de layout verandert.
4. Single Page Applications (SPA’s)
Bij SPA’s verandert de inhoud zonder paginareload.
Daarom moet Tolkie opnieuw worden geïnitialiseerd bij route- of paginawissels.
Dit kan op 2 manieren worden geregeld:
Door Tolkie: dan wordt het Tolkie-script herladen zodra de url verandert
Door de webbouwer: door
window.tolkie.init()aan te roepen als de nieuwe content in de DOM staat
Zo voorkom je dat de leeshulp werkt met verouderde content.
5. Content Security Policy (CSP)
Als de website een Content Security Policy gebruikt, moet Tolkie expliciet worden toegestaan.
Zonder aanpassing kan het script niet laden of werken functies zoals voorlezen niet correct.
In de meeste gevallen moet je de volgende directives uitbreiden:
style-src 'self' https://app.tolkie.nl https://cdn.tolkie.nl;
script-src 'self' https://app.tolkie.nl;
connect-src https://app.tolkie.nl https://api.tolkie.nl;
frame-src https://app.tolkie.nl;
img-src data: https://app.tolkie.nl https://cdn.tolkie.nl;
font-src https://app.tolkie.nl;
6. Eventueel: de styling van de knoppen aanpassen
De knoppen van Tolkie hebben een standaard opmaak. Je kunt css-regels toevoegen om het uiterlijk van de knoppen aan te passen. Zo kun je ervoor zorgen dat leeshulp beter aansluit bij het ontwerp van de website.
Wil je alleen de kleur aanpassen? Dat kan via Mijn Tolkie.
Andere instellingen: Mijn Tolkie
Klanten krijgen standaard toegang tot Mijn Tolkie. Daar kunnen ze allerlei dingen zelf regelen. Zoals:
Functies uitschakelen op bepaalde pagina's
De uitleg van woorden aanpassen
De simpele tekst (samenvatting) van een pagina aanpassen
Deze instellingen beïnvloeden de werking van de leeshulp, maar hoeven niet door de webbouwer te worden geïmplementeerd.
Bekijk ook het kennisbank-onderdeel over Mijn Tolkie.
Samenvatting voor webbouwers
Je zorgt als webbouwer voor:
het correct laden van het Tolkie-script;
een stabiele plek voor de knoppen in de layout;
herinitialisatie bij SPA-navigatie;
juiste CSP-instellingen.
De klant bepaalt samen met Tolkie de variant en functies, Tolkie regelt de configuratie, en jij zorgt dat de leeshulp technisch probleemloos werkt op de website.