What you need
Your own theme or subtheme with file access and permission to clear all caches. Do not change a core or contrib theme directly. In Accessonaut, first create a project with your actual website domain and open the installation page in the project.
Step by step
- Open the
THEMENAME.libraries.ymlfile of your own theme or subtheme. A subtheme survives updates to the base theme. - Create a library, for example
accessonaut, and add the public widget.js address underjswithtype: external. - Under
attributes, copy the attributes of your embed code:defer: trueand the data attributes such asdata-project-idwith the values from your project. - Attach the library globally in
THEMENAME.info.ymlunderlibraries:. Drupal loads JavaScript in the footer by default. - Clear all caches under Configuration → Development → Performance or with
drush cr. Check the public website with the active theme.
What the embed looks like
Use the ready-made code from your project. The example needs your real project ID and the publicly reachable service address.
<script src="https://accessonaut.com/widget.js"
data-project-id="YOUR_PROJECT_ID"
data-language="en" defer></script>Match the design to your website
In your Accessonaut project, open “Reading-aid widget”. Five templates and a live preview help you with the design: colours, fonts, menu width, corners, shadows, an icon or labelled opener and your own texts. Position and edge spacing can be set separately for desktop and smartphone. After saving, your existing embed code picks up the project design automatically; the public configuration is cached for up to one minute.
In the WordPress plugin you can choose local settings instead. These take priority over the project design. Design options are available on all plans. On the Free plan, the Accessonaut notice stays visible. Your visitors’ personal reading settings take priority over design defaults.
Keep in mind
The library only applies to themes that attach it. If you use other frontend themes, attach it there too. Do not paste the code into blocks with a text editor: text formats and the editor can remove script tags. You also need to clear page caches, reverse proxies and CDNs.
Common questions about Drupal
Do I need to switch off JavaScript aggregation?
No. Drupal does not combine external libraries with other files. The “Aggregate JavaScript files” option under Configuration → Development → Performance can stay on.
Can I attach the library in a template instead?
Yes. Instead of attaching it globally in THEMENAME.info.yml, you can load it in a Twig template with {{ attach_library('THEMENAME/accessonaut') }}. For a widget on every page, use a template that every page uses. Attach the library in only one of the two ways.
Do I need a separate embed for several languages?
No, as long as all languages use the same theme. With data-language="auto", the widget follows the page’s lang attribute. It speaks German, English and Spanish.
How do I remove the widget again?
Remove the library from THEMENAME.info.yml and from templates using attach_library. Delete the entry in THEMENAME.libraries.yml and clear all caches, for example with drush cr.
If something does not work
The script is missing from the page source.
Cause: Drupal has not reread the changed YAML files yet, or the name under libraries: does not match the library.
Fix: Clear all caches. Check that the entry reads exactly THEMENAME/accessonaut and that the indentation in the YAML files is correct.
The script loads, but without data-project-id.
Cause: The attributes are not under the file entry of the widget.js address.
Fix: Put attributes directly under the address, next to type: external. Drupal only applies values given there to the script element.
The widget shows the default design with the Accessonaut notice.
Cause: The website runs on a different domain from the one in the project, for example a development environment.
Fix: Check the design on the live domain. For a permanent second domain, create a separate project.
Check the installation
- Open the public website in a private window. The widget appears exactly once.
- Reach the button with the keyboard. Open the panel, change the text size and close it again.
- Check the homepage, a subpage, a form and the mobile view. The widget must not cover any important controls.
- In the Network tab, check that widget.js and the project configuration load from your service address. If there are errors, check the domain, project ID and CSP.
- For Free projects, the visible Accessonaut notice remains part of the widget. Permissions come from your project.
Privacy and limits
When it loads, the visitor’s browser fetches the script and the project configuration from the Accessonaut service. This involves the IP address, browser request data and the website hostname. Display preferences are stored locally in the browser. Cover the integration in your privacy notice and check your specific configuration.
The reading aids do not guarantee conformance. Also check barriers in the source code and complete user journeys, both automatically and manually.
Official platform documentation
Drupal: Adding CSS and JavaScript to a theme via libraries.yml