👨‍🔧️ Driver

Highlighting a Single Element – Without Popover

If all you want is just highlight a single element, you can do that simply by passing the selector

const driver = new Driver();
driver.highlight('#create-post');

A real world use-case for this could be highlighting an element when user is interacting with it

const focusDriver = new Driver();

// Highlight the section on focus
document.getElementById('creation-input')
  .addEventListener('focus', (e) => {
    focusDriver.focus('#creation-input');
  });

Focus any of the inputs and see how it moves the highlight from one element to the other

Highlighting a Single Element – With Popover

If you would like to show some details alongside the highlighted element, you can do that easily by specifying title and description

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
    title: 'Title for the Popover',
    description: 'Description for it',
  }
});

You can modify the behavior of this popover also by a certain set of options. More on it below.

Popover Positioning

You can also, change the position of the popover to be either left, top, right or bottom.

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
    title: 'Title for the Popover',
    description: 'Description for it',
    position: 'left', // can be `top`, `left`, `right`, `bottom`
  }
});

If you don't specify the position or specify it to be auto, it will automatically find the suitable position for the popover and show it

HTML in Popovers

You can also specify HTML in the body or the title of the popovers. Here is an example:

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
    title: '<em>An italicized title</em>',
    description: 'Description may also contain <strong>HTML</strong>'
  }
});

Creating Feature Introductions

You can also make powerful feature introductions to guide the users about the features. Just provide an array of steps where each step specifies an element to highlight.

Below is just a quick example showing you how to combine the steps in introduction.

Without Overlay

You can create feature introductions and do everything listed above without overlays also. All you have to do is just set the opacity to `0`.

const driver = new Driver({
    opacity: 0,
});

driver.highlight({
  element: '#run-element-without-popover',
  popover: {
    title: 'Title for the Popover',
    description: 'Description for it',
    position: 'top', // can be `top`, `left`, `right`, `bottom`
  }
});

..and you can do the same for the feature introductions

Driver Definition

Here are the options that Driver understands

const driver = new Driver({
  animate: true,  // Animate while changing highlighted element
  opacity: 0.75,  // Background opacity (0 means only popovers and without overlay)
  padding: 10,    // Distance of element from around the edges
  onHighlightStarted: (Element) {}, // Called when element is about to be highlighted
  onHighlighted: (Element) {}, // Called when element is fully highlighted
  onDeselected: (Element) {}, // Called when element has been deselected
});

Step Definition

Here are the set of options that you can pass in each step i.e. an item in array of steps or the object that you pass to highlight method

const stepDefinition = {
  element: '#some-item', // Query selector for the item to be highlighted
  popover: {             // There will be no popover if empty or not given
    title: 'Title',      // Title on the popover
    description: 'Description', // Body of the popover
    showButtons: false,      // Do not show control buttons in footer
    doneBtnText: 'Done',     // Text on the last button
    closeBtnText: 'Close',   // Text on the close button
    nextBtnText: 'Next',     // Next button text
    prevBtnText: 'Previous', // Previous button text
  }
};

API Methods

Below are the set of methods that are available to you

const driver = new Driver(driverOptions);

const isActivated = driver.isActivated; // Checks if the driver is active or not
driver.moveNext();     // Moves to next step in the steps list
driver.movePrevious(); // Moves to previous step in the steps list
driver.start(stepNumber = 0);  // Starts driving through the defined steps
driver.highlight(string|stepDefinition); // highlights the element using query selector or the step definition
driver.reset(); // Resets the overlay and clears the screen
driver.hasHighlightedElement(); // Checks if there is any highlighted element
driver.hasNextStep(); // Checks if there is next step to move to
driver.hasPreviousStep(); // Checks if there is previous step to move to

// Gets the currently highlighted element on screen
const activeElement = driver.getHighlightedElement();
const lastActiveElement = driver.getLastHighlightedElement();
activeElement.getScreenCoordinates(); // Gets screen co-ordinates of the active element
activeElement.hidePopover();  // Hide the popover
activeElement.showPopover();  // Show the popover

activeElement.getNode();  // Gets the DOM Element behind this element