Web site reader
This reader is created for reading static web page content out loud, for example blog texts or instructions. The reader does not support reading out loud dynamically changing content, such as web applications.
Instructions
1. Configure player settings in the customer portal
Go to the customer portal at https://portal.aimater.com/ and log in. Navigate to the Reader page. Adjust the reader settings as you want the player to behave. Use the preview to find the desired result. Finally, save the settings, and copy the script code from the bottom of the page.
2. Import the reader script to your web page
Import the reader script into you web page by pasting the copied code into your web page, at the end of the <head> section, for example.
...
<script src="https://portal.aimater.com/static/reader/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.js"></script>
</head>
3. Mark the readable text content in your web page
In your web page source code, add the class 'aim-readable' to the element(s) that you want the reader to read out loud.
<article class="aim-readable">
This article content is read out loud.
</article>
That's all you need for the reader to start detecting readable content and to place an audio player into your web page.
Read the Notes section for additional notes and instructions.
Notes
Readable elements
All text content that should be read out loud, must be inside an element with the class 'aim-readable'. Add this class only to the parent element, not all child elements. You may add this class to sibling elements. For example:
<article class="aim-readable">
<h1>...</h1>
<p>...</p>
<p>...</p>
</article>
<div class="author aim-readable"></div>
Skipped elements
If you want to skip some text content, inside the 'aim-readable' element, from being read out loud, add the class 'aim-skip' to that element.
On default, all hidden and aria-hidden elements are automatically skipped. Also all <button>, <canvas>, <nav> and <script> elements are skipped.
If you want to force the reader to read out loud a skipped element, add the class 'aim-include' into that element.
For example:
<article class="aim-readable">
<nav class="aim-include">...</nav> <!-- Included -->
<h1>...</h1> <!-- Included -->
<p>...</p> <!-- Included -->
<div class="aim-skip">...</div> <!-- Skipped -->
<button>...</button> <!-- Skipped -->
</article>
Player position
Default position
On default, the reader looks for the first heading element inside the first 'aim-readable' element, and places the player below the heading.
<article class="aim-readable">
<h1>Article heading</h1>
<aside class="aim-player-container">
<!-- This player element is inserted. -->
</aside>
...
</article>
If no headings are found in the beginning of the 'aim-readable' element, the player will be inserted directly inside the 'aim-readable' element, as the first child. For example:
<article class="aim-readable">
<aside class="aim-player-container">
<!-- This player element is inserted. -->
</aside>
...
</article>
Custom position
If you want to set a custom position for the player, you can use the portal settings to define a target element id for the player. The player will then be inserted to the element with the given id.
<article class="aim-readable">...</article>
<div id="my-player-container">
<aside class="aim-player-container">
<!-- This player element is inserted. -->
<!-- Controls the above 'aim-readable' element. -->
</aside>
</div>
You can also change the default position directly in the HTML code, by providing a data-aim-player-target-element attribute for the 'aim-readable' element. Give the element id in this attribute, and the player will be inserted inside that element.
<article class="aim-readable" data-aim-player-target-element="my-player-container">...</article>
<div id="my-player-container">
<aside class="aim-player-container">
<!-- This player element is inserted. -->
<!-- Controls the above 'aim-readable' element. -->
</aside>
</div>
Media keys
Using the reader adds support for using media keys on the audio playback. For example the Play or Pause buttons on a multimedia keyboard will work on the audio playback.
Custom player
If you don't want to use the available audio player, the player can also be customized. Ask the a.i.mater organization for more instructions on this.
Warnings
Does not support dynamic content
This script is not intended to be used on text content, that can dynamically change. The text content inside the 'aim-readable' elements is read only once in the beginning, and further modifications to the text content are not detected.
Highlighting text in a single-page application (SPA)
This warning is relevant to you, if you are using Angular, React, Vue or other single-page application framework.
The text highlighting is done by modifying the HTML document. This might cause errors in SPAs, while the highlighting is active. The errors occur because some text nodes, that the SPA has rendered, will be temporarily removed. Once the highlighting has finished, the original text nodes are returned to the document. Be sure to test your application well, when using this script with a SPA.