PageGuide By Diligentia-Uitgeverij

Why did we create another library?

There are loads of libraries that are dedicated to highlight certain elements in a page, and adding a popup next to this element. Why would we need to create another?

Our applications are all quite heavy HTML-wise, with containers having z-indexes and elements within these containers also can have their z-indexes defined. This means that you can't set a target's z-index to 9999999, and expect it to come on top of the application.
For instance hit the button to start a guide with intro.js
Because z-indexes are a mystical behaviour for most, here is a nice article that explains this behaviour. Z-index demystified.

So how did we fix this problem in our own library? By adding a canvas on top of the entire application. On this canvas we draw the backdrop, and then we mask out the targets.

This ensures that the element is highlighted, even on z-index-heavy applications. And it has some other improvements to the more classic libraries. For instance, highlighting multiple targets is now easily possible, they just have to fit in the viewport.

You can start the guide by clicking on the button in the header, or by clicking this button right here:

Basic usage

There are a couple of different ways to get started. But in the most basic way, simply include the script on your page, and add the following code.

var guideElements = [
  {
    title: 'A title',
    content: 'Content is the only required field.',
    element: '#target',
    postion: 'bottom',
    shape: 'rect',
  },
];

var pageGuide = new PageGuide.PageGuide(guideElements, false);
var btnStart = document.getElementById('btn-start');

btnStart.onclick = function() {
  pageGuide.start();
};

A GuideElement is defined as follows:

content string REQUIRED Content of the popup, can be any HTML, or just a simple string.
title string OPTIONAL The title of the popup.
element string OPTIONAL a querySelector, will be used as document.querySelector(guideElement.element);. If the querySelector is defined, but yields no result, the popup will be ignored.
If you don't supply an element, th epopup will simply be centered on the page.
position string OPTIONAL Pick the position of the popup relative to the first target. Options are:
  • top
  • right
  • bottom
  • left
shape string OPTIONAL pick a shape to highlight with. Options are:
  • rect
  • rounded_rect
  • circle
  • ellipse

Position

For the positioning of the popup we use the brilliant library Popper.js.

You can only specify the direction where you want the popup to be, Popper will reposition when necessary.

Shapes

This is one of the biggest advantages of using a canvas, we can easily define a shape to use as mask. For now we are limited to using a rectangle, a rounded rectangle, a circle, or an ellipse.

Would you like to add another shape? Feel free to open a pull-request on Github.

Multiple targets

You can target multiple elements in a single popup. The popup will position itself around the first found element.

To target a single element, give it an id on the page and supply the id as follows in your list: #id-of-the-target.
If you're targeting multiple elements, simply define the correct querySelector in your list. For instance: .common-class-of-the-targets or you could even target all elements in a list: ul.nav > li, ...

To check if you're providing the correct querySelector, you could simply open the console and try your selector live on your page: document.querySelector(guideElement.element)

Issues

If you found some issues, please notfiy us at Github Issues.