November 2021 - QetriX Blog

Monday, November 22, 2021

Tutorial System

After I finished Creator, I felt like it would deserve a topping of some sort. For one of my previous versions of Qedy I created a simple scripted tutorials on live web page, mostly for forms.

I decided it was good enough to be revived for the current version, because the Tutorial System featured:

Virtual mouse cursor (pointer), which is basically just an image, that moves around. Thanks to CSS transitions I can only set a target top + left coordinates and it travels there “by itself”. In the script I simply pass an element selector, the cursor will travel to center of it and wait for further instructions. So, it's usable in a responsive design as well.
Clicking of the cursor, thanks to sending custom mouse events. They aren't trusted, so some perks are inaccessible – like triggering CSS :hover on mouseover. I added a ripple-effect animation to it and a sound as well.
Typing, in a similar fashion as clicking. I created an animation for the typed characters to appear one by one and with random delay, to look more natural. After every typed letter it plays a “typewritter” sound.
User actions by adding event listeners to desired elements. For example, if it instructs the user to select specific option, it adds oninput event handler, where it checks for value and continues when the value is correct. The only concern here is for this handler to be called despite other handlers on the same element, which may include stopPropagation command.
Speech, using SpeechSynthesis service. And if the generated voice is not good enough, it's possible to play prerecorded audio files instead.

Tutorial in progress, showing also a red animated circle to emphasise a click.

At the bottom I added an overall progress indicator. It's animated using a CSS transition for width property set to 2.4 secs and it looks kinda nice. Most actions take around 2~3 secs (click, cursor move, short typing), so the bar is mostly moving, like a playback bar in a video player.

A hurdle I had to overcome is it's not possible to open a dropdown menu (SELECT) programmatically, so I had to create a virtual list of options and fake it as the real thing. It works for now, but it doesn't acquire proper styles, so it will look wrong on other themes and visual modes.

Another hurdle was changing the cursor to proper visual representation. I had just an arrow, but on buttons it looked weird. I didn't think it's worth the effort but changing to hand for some occasions wasn't actually that hard and greatly improved the overall impression.

The worst part was I had to fiddle with the hot spot (the point, under which the click happens). The arrow has it conveniently at [0, 0], but for the hand it's [6, 0], so I had to move some stuff a bit. I hope it won't bite me later. I won't do the I-beam text cursor though, it's even more hot spot shuffling.

When looking at the text while it's being read by the computer voice, I imagined it in a “karaoke” mode, when particular words will highlight in sync with the speech. I dismissed it as too difficult to time it correctly, but for purpose of writing this post I digged into API docs for the utterance.

There I found a boundary event, that is fired when the spoken utterance reaches a word or sentence boundary. To my surprise it's exactly what I needed. I only wrapped every word into SPAN and in the event method simple incremented index to get the correct DOM child, to which was assigned a proper CSS class. Done!

In case of an error, like the element selector became invalid or live operation caused a blank page, when the scripts detect problem, it apologizes and ends the course automatically. Meanwhile, in the background, it sends me a bug report.

Tutorial System

Ancestry