Skip to main content

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. diagram

Core Features

Tour Engine

PropertyTypeDefaultDescription
drive()MethodStarts the tour at the first step and displays the spotlight overlay
moveNext()MethodAdvances to the next tour step with smooth animation
movePrevious()MethodReturns to the previous tour step with smooth animation
moveTo(stepIndex)MethodJumps directly to a specific step by index (0-based)
destroy()MethodStops the tour, removes overlay and popovers, restores page interaction
onHighlightStarted(callback)EventFires before an element is highlighted; receives step configuration
onHighlighted(callback)EventFires after an element is highlighted and popover is displayed
onDeselected(callback)EventFires 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:
PropertyTypeDefaultDescription
elementString or ElementCSS selector (e.g., #theGrid) or direct DOM element reference for the active element
popover.titleStringHeading text displayed in the popover tooltip
popover.descriptionStringMain explanation text shown in the popover
popover.positionStringbottomPopover placement: top, bottom, left, right, center, or over
popover.showButtonsArray['next', 'previous', 'close']Which buttons to show: next, previous, close
popover.disableButtonsArray[]Which buttons to disable on this step (e.g., ['previous'] on first step)
popover.progressTextString{{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

PropertyTypeDefaultDescription
popover.showButtonsArray['next', 'previous', 'close']Display buttons: use next, previous, or close
popover.disableButtonsArray[]Disable specific buttons on this step to prevent navigation
popover.progressTextString{{current}} of {{total}}Customizable progress display; replace {{current}} and {{total}} with placeholders
popover.showProgressBooleantrueShow or hide the progress indicator
popover.alignStringstartPopover 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:
PropertyTypeDefaultDescription
stagePaddingNumber5Padding (in pixels) around the spotlighted element before the overlay darkens
stageRadiusNumber5Corner radius (in pixels) of the spotlight shape; 0 for sharp corners, higher for rounded
overlayOpacityNumber0.5Darkness of the overlay; 0.0 (transparent) to 1.0 (opaque)
allowCloseBooleantrueAllow users to close the tour by clicking the overlay or pressing Escape
disableActiveInteractionBooleanfalsePrevent interaction with the highlighted element during the tour

Keyboard Navigation

Driver.js supports full keyboard control for accessibility and power users:
KeyAction
TabCycle focus between tour buttons
Enter / SpaceActivate focused button (Next, Previous, Close)
Arrow RightNext step (if available)
Arrow LeftPrevious step (if available)
EscapeClose the tour
All keyboard events respect showButtons and disableButtons configuration, so steps can enforce certain navigation patterns.

Smooth Scrolling and Animation

PropertyTypeDefaultDescription
smoothScrollBooleantrueEnable smooth animated scrolling to bring the element into view
scrollDurationNumber300Duration (in milliseconds) of scroll animation
highlightAnimationDurationNumber500Duration (in milliseconds) for spotlight and popover to appear/disappear
useRequestAnimationFrameBooleantrueUse browser animation frames for smooth performance

Intelligent Popover Positioning

Driver.js automatically positions popovers to avoid viewport edges:
BehaviorDescription
Preferred PositionUses the position setting (top/bottom/left/right) if sufficient viewport space
Fallback DetectionIf preferred position would overflow, tries alternate positions in order: opposite side, perpendicular sides
Arrow AlignmentThe popover arrow indicator always points toward the highlighted element, even with fallback positions
Center PositionUse position: 'center' to overlay the popover directly on the element
Over PositionUse 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:
PropertyTypeDefaultDescription
stepsArrayArray of step objects; each step has element, popover, and optional lifecycle callbacks
highlightOpacityNumber0.5Overlay darkness (same as overlayOpacity); applied to all steps
stagePaddingNumber5Default padding around all spotlighted elements
stageRadiusNumber5Default corner radius for all spotlight shapes
smoothScrollBooleantrueEnable smooth scrolling for all steps
allowCloseBooleantrueAllow 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:
CallbackFiresParametersUse Case
onHighlightStarted(step)Before element is highlightedStep configuration objectPre-highlight setup (e.g., scroll to element)
onHighlighted(step)After element is highlightedStep configuration objectTrack analytics, enable dynamic content
onDeselected(step)When tour leaves this elementStep configuration objectCleanup, 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

BrowserMinimum VersionNotes
Chrome60+Full support including modern CSS
Firefox55+Full support
Safari12+Full support on macOS and iOS
Edge79+Full support (Chromium-based)
Internet ExplorerNot supportedDriver.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.

Performance Considerations

AspectRecommendation
Tour lengthKeep tours under 10 steps to maintain engagement; break long workflows into multiple tours
Animation timingUse 300–500ms animation durations for smooth feedback without feeling sluggish
Spotlight paddingUse 5–8px padding to give elements breathing room without overlapping adjacent elements
Overlay opacityUse 0.5–0.7 opacity; higher values may obscure important information, lower values weaken focus
Element selectionUse specific CSS selectors (e.g., #theGrid) rather than broad selectors (e.g., .grid) to avoid ambiguity
Callback logicKeep lifecycle callbacks lightweight; heavy processing in callbacks delays tour transitions

Accessibility Features

Driver.js includes built-in accessibility support:
FeatureImplementation
Keyboard navigationArrow keys, Tab, Escape fully navigate tours without mouse
ARIA attributesPopover elements include role="tooltip" and aria-label for screen readers
Focus managementTour buttons receive focus in logical order; Escape releases focus back to page
High contrastOverlay and spotlight have strong contrast ratios; popover text meets WCAG AA standards
Motion preferencesIf 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.