Overview
Driver.js is used by the Risksheet Tour Module to deliver first-time user onboarding for FMEA analysis. The library highlights UI elements one at a time, displays contextual help text in popovers, and darkens the rest of the page to focus attention. Tours are keyboard-navigable, accessible, and can be triggered automatically or manually.
Core Features
Tour Engine
| Property | Type | Default | Description |
|---|
drive() | Method | — | Starts the tour at the first step and displays the spotlight overlay |
moveNext() | Method | — | Advances to the next tour step with smooth animation |
movePrevious() | Method | — | Returns to the previous tour step with smooth animation |
moveTo(stepIndex) | Method | — | Jumps directly to a specific step by index (0-based) |
destroy() | Method | — | Stops the tour, removes overlay and popovers, restores page interaction |
onHighlightStarted(callback) | Event | — | Fires before an element is highlighted; receives step configuration |
onHighlighted(callback) | Event | — | Fires after an element is highlighted and popover is displayed |
onDeselected(callback) | Event | — | Fires when the tour moves away from the current element |
Step Configuration
Each tour step defines which element to highlight, what message to display, and how to behave:
| Property | Type | Default | Description |
|---|
element | String or Element | — | CSS selector (e.g., #theGrid) or direct DOM element reference for the active element |
popover.title | String | — | Heading text displayed in the popover tooltip |
popover.description | String | — | Main explanation text shown in the popover |
popover.position | String | bottom | Popover placement: top, bottom, left, right, center, or over |
popover.showButtons | Array | ['next', 'previous', 'close'] | Which buttons to show: next, previous, close |
popover.disableButtons | Array | [] | Which buttons to disable on this step (e.g., ['previous'] on first step) |
popover.progressText | String | {{current}} of {{total}} | Progress indicator text; use {{current}} and {{total}} placeholders |
Example step configuration:
{
element: '#btnColumns',
popover: {
title: 'Switch Views',
description: 'Click here to show or hide columns. Focus on pre-mitigation, post-mitigation, or specific FMEA aspects.',
position: 'bottom',
showButtons: ['next', 'previous', 'close'],
progressText: 'Step {{current}} of {{total}}'
}
}
Popover Customization
| Property | Type | Default | Description |
|---|
popover.showButtons | Array | ['next', 'previous', 'close'] | Display buttons: use next, previous, or close |
popover.disableButtons | Array | [] | Disable specific buttons on this step to prevent navigation |
popover.progressText | String | {{current}} of {{total}} | Customizable progress display; replace {{current}} and {{total}} with placeholders |
popover.showProgress | Boolean | true | Show or hide the progress indicator |
popover.align | String | start | Popover alignment relative to element: start, center, or end |
Element Highlighting and Overlay
Driver.js darkens the entire page using an SVG overlay and displays a spotlighted circle around the active element:
| Property | Type | Default | Description |
|---|
stagePadding | Number | 5 | Padding (in pixels) around the spotlighted element before the overlay darkens |
stageRadius | Number | 5 | Corner radius (in pixels) of the spotlight shape; 0 for sharp corners, higher for rounded |
overlayOpacity | Number | 0.5 | Darkness of the overlay; 0.0 (transparent) to 1.0 (opaque) |
allowClose | Boolean | true | Allow users to close the tour by clicking the overlay or pressing Escape |
disableActiveInteraction | Boolean | false | Prevent interaction with the highlighted element during the tour |
Keyboard Navigation
Driver.js supports full keyboard control for accessibility and power users:
| Key | Action |
|---|
Tab | Cycle focus between tour buttons |
Enter / Space | Activate focused button (Next, Previous, Close) |
Arrow Right | Next step (if available) |
Arrow Left | Previous step (if available) |
Escape | Close the tour |
All keyboard events respect showButtons and disableButtons configuration, so steps can enforce certain navigation patterns.
| Property | Type | Default | Description |
|---|
smoothScroll | Boolean | true | Enable smooth animated scrolling to bring the element into view |
scrollDuration | Number | 300 | Duration (in milliseconds) of scroll animation |
highlightAnimationDuration | Number | 500 | Duration (in milliseconds) for spotlight and popover to appear/disappear |
useRequestAnimationFrame | Boolean | true | Use browser animation frames for smooth performance |
Intelligent Popover Positioning
Driver.js automatically positions popovers to avoid viewport edges:
| Behavior | Description |
|---|
| Preferred Position | Uses the position setting (top/bottom/left/right) if sufficient viewport space |
| Fallback Detection | If preferred position would overflow, tries alternate positions in order: opposite side, perpendicular sides |
| Arrow Alignment | The popover arrow indicator always points toward the highlighted element, even with fallback positions |
| Center Position | Use position: 'center' to overlay the popover directly on the element |
| Over Position | Use position: 'over' to display the popover as a fixed-position label without arrows |
Example: Position priority logic
Requested: bottom
├─ Sufficient space below? → Use bottom
├─ No → Sufficient space above? → Use top
├─ No → Sufficient space to right? → Use right
├─ No → Use left
└─ Still no space? → Use center (overlay on element)
Tour Structure and Lifecycle
Defining a Complete Tour
A tour is an array of step configurations with optional global settings:
| Property | Type | Default | Description |
|---|
steps | Array | — | Array of step objects; each step has element, popover, and optional lifecycle callbacks |
highlightOpacity | Number | 0.5 | Overlay darkness (same as overlayOpacity); applied to all steps |
stagePadding | Number | 5 | Default padding around all spotlighted elements |
stageRadius | Number | 5 | Default corner radius for all spotlight shapes |
smoothScroll | Boolean | true | Enable smooth scrolling for all steps |
allowClose | Boolean | true | Allow closing tour via overlay click or Escape |
Example tour definition:
const risksheetTour = {
steps: [
{
element: '#nxtr-topPanel .rs-green-colored',
popover: {
title: 'Welcome to Risksheet',
description: 'Risksheet is a spreadsheet-like editor for FMEA with 1:1 LiveDoc sync. Changes here automatically update the Polarion document.',
position: 'bottom',
showButtons: ['next', 'close']
}
},
{
element: '#theGrid',
popover: {
title: 'Risk Analysis Grid',
description: 'The main FMEA grid displays failure modes, effects, causes, and risk assessments in an Excel-like spreadsheet. Click cells to edit directly.',
position: 'bottom'
}
},
{
element: '#btnColumns',
popover: {
title: 'Switch Views',
description: 'Click to show or hide columns focusing on pre-mitigation, post-mitigation, or specific FMEA aspects.',
position: 'bottom'
}
}
],
stagePadding: 8,
stageRadius: 4,
smoothScroll: true
};
const tour = new Driver(risksheetTour);
tour.drive();
Lifecycle Callbacks
Each step can define callbacks that fire at specific moments during tour execution:
| Callback | Fires | Parameters | Use Case |
|---|
onHighlightStarted(step) | Before element is highlighted | Step configuration object | Pre-highlight setup (e.g., scroll to element) |
onHighlighted(step) | After element is highlighted | Step configuration object | Track analytics, enable dynamic content |
onDeselected(step) | When tour leaves this element | Step configuration object | Cleanup, restore element state |
Example with callbacks:
{
element: '#theGrid',
popover: { /* ... */ },
onHighlighted: (step) => {
console.log('Grid is now highlighted');
document.getElementById('theGrid').classList.add('tour-active');
},
onDeselected: (step) => {
document.getElementById('theGrid').classList.remove('tour-active');
}
}
Integration with Risksheet
The Risksheet Tour Module wraps Driver.js with auto-initialization, localStorage persistence, and Nextedy-specific tour content. Most users do not interact with Driver.js directly—the tour module handles all setup.
The Risksheet Tour Module (risksheet-tour.js) uses Driver.js to provide:
- 8-step intro tour for first-time users covering Risksheet identity, grid editing, views, filtering, add buttons, traffic lights, and completion tracking
- 3-step short tour for help button clicks focusing on traffic light status indicators
- Auto-detection of first-time users via localStorage (
tour-seen-{tourId})
- Manual restart via footer button in Risksheet
The module configures Driver.js with TestAuto2-specific styling, positioning logic for Wijmo FlexGrid elements, and Polarion page layouts.
Browser Support
| Browser | Minimum Version | Notes |
|---|
| Chrome | 60+ | Full support including modern CSS |
| Firefox | 55+ | Full support |
| Safari | 12+ | Full support on macOS and iOS |
| Edge | 79+ | Full support (Chromium-based) |
| Internet Explorer | Not supported | Driver.js requires modern JavaScript (ES6+) |
Driver.js requires JavaScript to be enabled in the browser. If JavaScript is disabled, tours will not load. All tour navigation relies on JavaScript event listeners.
| Aspect | Recommendation |
|---|
| Tour length | Keep tours under 10 steps to maintain engagement; break long workflows into multiple tours |
| Animation timing | Use 300–500ms animation durations for smooth feedback without feeling sluggish |
| Spotlight padding | Use 5–8px padding to give elements breathing room without overlapping adjacent elements |
| Overlay opacity | Use 0.5–0.7 opacity; higher values may obscure important information, lower values weaken focus |
| Element selection | Use specific CSS selectors (e.g., #theGrid) rather than broad selectors (e.g., .grid) to avoid ambiguity |
| Callback logic | Keep lifecycle callbacks lightweight; heavy processing in callbacks delays tour transitions |
Accessibility Features
Driver.js includes built-in accessibility support:
| Feature | Implementation |
|---|
| Keyboard navigation | Arrow keys, Tab, Escape fully navigate tours without mouse |
| ARIA attributes | Popover elements include role="tooltip" and aria-label for screen readers |
| Focus management | Tour buttons receive focus in logical order; Escape releases focus back to page |
| High contrast | Overlay and spotlight have strong contrast ratios; popover text meets WCAG AA standards |
| Motion preferences | If user has prefers-reduced-motion set, animations are disabled |
Tour popovers are announced to screen readers, allowing visually impaired users to follow tour steps. Ensure popover descriptions are concise and descriptive.
Related Pages