What you need
Contao 5.7 or 5.3 LTS or Contao 6.0 with the matching PHP version, the Contao Manager or Composer and a backend account that may edit website roots. For Contao 4.13, use the manual embed from the questions below. In Accessonaut, first create a project with your actual website domain and open the installation page in the project.
Step by step
- Install the bundle from the section “The Contao bundle” below, in the Contao Manager or with Composer.
- Update the database when the Contao Manager asks you to, or run
vendor/bin/contao-console contao:migrate. The bundle adds four fields to the website root. - In the backend, open Content → Pages and edit the website root. In the “Accessonaut reading aids” section, tick “Enable the widget and the connection to the service”.
- Enter the public project ID from the installation page of your Accessonaut project and keep the service address https://accessonaut.com. Read the note on the external service and save. Repeat this for every website root that should show the widget. Then check several public subpages in a private window.
The Contao bundle
The bundle “accessonaut/contao-accessibility” adds the script for you, without changes to page layouts or templates. It runs on Contao 5.7 and 5.3 LTS as well as 6.0 and starts switched off on every website root page. Only when you switch it on and enter a valid project ID does the browser load anything from the service. Every website of an installation has its own settings. The widget never appears in the back end.
accessonaut-contao-1.0.0.zip
SHA-256 checksum · Licence: GPLv2 or later
Listing on Packagist and in the Contao extension list is prepared. Until then, upload the ZIP file in the Contao Manager under Packages → “Upload Packages”, choose “Confirm Uploads” and then “Apply Changes”. With Composer, install it as a local package:
mkdir -p packages
cp ~/Downloads/accessonaut-contao-1.0.0.zip packages/
composer config repositories.accessonaut artifact ./packages
composer require accessonaut/contao-accessibility:^1.0
vendor/bin/contao-console contao:migrateWithout the extension or bundle you can still add the embed code yourself. It is shown in the next section; the common questions further down explain how.
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
Use exactly one installation method and remove the embed code from the custom JavaScript code of your page layouts. If the bundle already finds a script of the same service on a page, it does not add a second one. It adds the script to the finished page and therefore needs no field in the page layout, not even with Twig layouts. You need to clear upstream proxies and CDNs yourself.
Common questions about Contao
How do I add the widget without the bundle?
Open Layout → Themes and the page layouts of your theme. In the JavaScript section, paste the unchanged embed code into the field for your own JavaScript code; Contao outputs it at the end of the page. If your pages use several layouts, add it to each of them exactly once. The Twig layout type with slots has no such field. This also applies to Contao 4.13.
What applies with several websites in one installation?
Every website root has its own Accessonaut settings. If the websites use different domains, each needs its own Accessonaut project. Enter its project ID in the matching website root. Websites without the tick show no widget.
What do I need to do with Contao’s Content Security Policy?
From Contao 5.3, you enable CSP in the website root. The Content Security Policy field contains the whole header. Add your service address to script-src and connect-src. The widget inserts style elements without a nonce; style-src must allow inline styles. Test with reporting-only mode first.
Do I need to clear the cache after saving?
Usually not. Contao links cached pages to their parent pages. When you save the website root, Contao discards the pages of this website from the shared cache. Clear upstream proxies and CDNs separately.
How do I remove the widget again?
Untick the box in the website root and save. To remove the bundle completely, uninstall it in the Contao Manager or with composer remove accessonaut/contao-accessibility. The database update then offers to delete the four fields. Also remove CSP entries you only added for the widget.
If something does not work
The widget is missing.
Cause: The box is not ticked in the website root of this domain, the project ID has an invalid format or an upstream cache still serves the old page.
Fix: Check the fields of the correct website root. The project ID consists of 20 to 40 lowercase letters and digits. Clear proxies and CDNs.
The browser console reports a CSP violation.
Cause: The CSP of the website root does not allow your service address or the widget’s styles.
Fix: Add the missing source to the reported directive and save the website root.
An older embed keeps working and changes in the bundle have no effect.
Cause: The embed code is still in the custom JavaScript code of a page layout. The bundle then does not add a second script.
Fix: Delete the old embed code from all page layouts and save them.
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.