|
|
<!doctype html> |
|
|
<html lang="en"> |
|
|
<head> |
|
|
<meta charset="UTF-8"> |
|
|
<meta name="viewport" |
|
|
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"> |
|
|
<meta http-equiv="X-UA-Compatible" content="ie=edge"> |
|
|
<title>Driver</title> |
|
|
<meta name=description itemprop=description |
|
|
content="A light-weight, no-dependency, vanilla JavaScript library to drive the user's focus across the page"/> |
|
|
<link rel="stylesheet" href="./dist/demo.css"> |
|
|
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/monokai.min.css"> |
|
|
</head> |
|
|
<body> |
|
|
<div class="page-wrap"> |
|
|
<section class="section__header" id="driver-demo-head"> |
|
|
<h1><span id="logo_emoji" class="emoji">👨🔧️</span> <span id="name_driver">Driver</span></h1> |
|
|
<p class="text-muted">A light-weight, no-dependency, vanilla JavaScript library to drive the user's focus across the |
|
|
page</p> |
|
|
<a href="javascript:void(0)" class="btn btn__example btn__dark">Quick Tour</a> |
|
|
</section> |
|
|
|
|
|
<blockquote> |
|
|
<p>A lightweight (~4kb gzipped) yet powerful JavaScript engine that helps you drive the user's focus on page.</p> |
|
|
<p class="zero-bottom">Some sample use-cases can be creating powerful feature introductions, call-to-action |
|
|
components, focus shifters etc.</p> |
|
|
</blockquote> |
|
|
|
|
|
<section class="section__purpose"> |
|
|
<h3>What are the features?</h3> |
|
|
<p>Driver is compatible with all the major browsers and can be used for any of your overlay needs. Feature |
|
|
introductions, focus shifters, call-to-action are just a few examples.</p> |
|
|
<ul> |
|
|
<li id="highlight_feature">🔆 <strong>Highlight</strong> any (literally any) item on page</li> |
|
|
<li id="interactions_feature">✋ <strong>Block user interactions</strong></li> |
|
|
<li id="feature_introductions_feature">📣 Create <strong>feature introductions</strong></li> |
|
|
<li id="focus_shifters_feature">👓 Add <strong>focus shifters</strong> for users</li> |
|
|
<li id="customizable_feature">🛠️ Highly customizable – <strong>Use it anywhere</strong> for overlay</li> |
|
|
<li id="keyboard_feature">⌨️ User Friendly – <strong>Controllable by keys</strong></li> |
|
|
<li id="free_use_feature">🆓 <strong>MIT Licensed</strong> – Free for personal and commercial use</li> |
|
|
<li id="lightweight_feature">🕊️ Lightweight – Only <strong>~4kb</strong> when gzipped</li> |
|
|
<li id="major_browsers_feature">🌀 <strong>Consistent behavior</strong> across all major browsers</li> |
|
|
</ul> |
|
|
</section> |
|
|
<hr class="hr__fancy"> |
|
|
<section class="section__how"> |
|
|
<h3>How does it do that?</h3> |
|
|
<p>In it simplest, it puts the canvas on top of the whole page and then cuts the part that is over the element to be |
|
|
highlighted and provides you several hooks when highlighting, highlighted or un-highlighting elements making it |
|
|
highly customizable.</p> |
|
|
</section> |
|
|
<hr class="hr__fancy"> |
|
|
<section class="section__examples"> |
|
|
<div id="examples_section"> |
|
|
<h3>Can you show some Examples?</h3> |
|
|
<p>Below you find some of the examples and sample use-cases on how you can use it. Run by clicking the |
|
|
<code>RUN</code> button.</p> |
|
|
</div> |
|
|
<div id="single-element-no-popover" class="section__example"> |
|
|
<h4>Highlighting a Single Element – Without Popover</h4> |
|
|
<p class="zero-bottom">If all you want is just highlight a single element, you can do that simply by passing the |
|
|
selector</p> |
|
|
<a href="#" class="btn__run-demo" id="run-single-element-no-popover">Show Demo</a> |
|
|
<pre><code class="javascript">const driver = new Driver(); |
|
|
driver.highlight('#create-post'); |
|
|
</code></pre> |
|
|
</div> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div class="section__example"> |
|
|
<p>A <strong>real world use-case</strong> for this could be highlighting an element when user is interacting with |
|
|
it</p> |
|
|
<pre><code class="javascript">const focusDriver = new Driver(); |
|
|
|
|
|
// Highlight the section on focus |
|
|
document.getElementById('creation-input') |
|
|
.addEventListener('focus', (e) => { |
|
|
focusDriver.focus('#creation-input'); |
|
|
}); |
|
|
</code></pre> |
|
|
<p class="top-20">Focus any of the inputs and see how it moves the highlight from one element to the other</p> |
|
|
<div id="creation-forms"> |
|
|
<input type="text" id="creation-input" class="form-control" placeholder="Focus any of the inputs"> |
|
|
<input type="text" id="creation-input-2" class="form-control" placeholder="Focus any of the inputs"> |
|
|
<input type="text" id="creation-input-3" class="form-control" placeholder="Focus any of the inputs"> |
|
|
<input type="text" id="creation-input-4" class="form-control" placeholder="Focus any of the inputs"> |
|
|
</div> |
|
|
</div> |
|
|
|
|
|
<p>You can also turn off the animation or set the padding around the corner. More on it later.</p> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div id="single-element-with-popover" class="section__example"> |
|
|
<h4>Highlighting a Single Element – With Popover</h4> |
|
|
<p>If you would like to show some details alongside the highlighted element, you can do that easily by specifying |
|
|
title and description</p> |
|
|
<a href="#" class="btn__run-demo" id="run-single-element-with-popover">Show Demo</a> |
|
|
<pre><code class="javascript">const driver = new Driver(); |
|
|
driver.highlight({ |
|
|
element: '#some-element', |
|
|
popover: { |
|
|
title: 'Title for the Popover', |
|
|
description: 'Description for it', |
|
|
} |
|
|
}); |
|
|
</code></pre> |
|
|
<p class="top-20">You can modify the behavior of this popover also by a certain set of options. More on it |
|
|
below.</p> |
|
|
</div> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div id="single-element-with-popover-position" class="section__example"> |
|
|
<h4>Popover Positioning</h4> |
|
|
<p>You can also, change the position of the popover to be either <code>left</code>, <code>top</code>, |
|
|
<code>right</code> or <code>bottom</code>.</p> |
|
|
<a href="#" class="btn__run-demo" id="run-single-element-with-popover-position">Show Demo</a> |
|
|
<pre><code class="javascript">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` |
|
|
} |
|
|
}); |
|
|
</code></pre> |
|
|
</div> |
|
|
<div class="section__example"> |
|
|
<div class="top-20 position-btns"> |
|
|
<a href="#" id="position-btn-left">On my Left</a> |
|
|
<a href="#" id="position-btn-top">On my Top</a> |
|
|
<a href="#" id="position-btn-bottom">On my Bottom</a> |
|
|
<a href="#" id="position-btn-right">On my Right</a> |
|
|
</div> |
|
|
<p class="top-20">If you don't specify the position or specify it to be <code>auto</code>, it will automatically |
|
|
find the suitable position for the popover and show it</p> |
|
|
</div> |
|
|
<hr class="hr__fancy"> |
|
|
<div id="single-element-with-popover-html" class="section__example"> |
|
|
<h4>HTML in Popovers</h4> |
|
|
<p>You can also specify HTML in the body or the title of the popovers. Here is an example:</p> |
|
|
<a href="#" class="btn__run-demo" id="run-single-element-with-popover-html">Show Demo</a> |
|
|
<pre><code class="javascript">const driver = new Driver(); |
|
|
driver.highlight({ |
|
|
element: '#some-element', |
|
|
popover: { |
|
|
title: '<em>An italicized title</em>', |
|
|
description: 'Description may also contain <strong>HTML</strong>' |
|
|
} |
|
|
}); |
|
|
</code></pre> |
|
|
</div> |
|
|
|
|
|
<p class="top-20">And of-course it can be any valid HTML.</p> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div id="third-element-introduction" class="section__example"> |
|
|
<h4 id="first-element-introduction">Creating Feature Introductions</h4> |
|
|
<p id="second-para-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.</p> |
|
|
<p id="third-para-feature-introductions">Below is just a quick example showing you how to combine the steps in |
|
|
introduction.</p> |
|
|
<a href="#" class="btn__run-demo" id="run-multi-element-popovers">Show Demo</a> |
|
|
</div> |
|
|
<pre><code class="javascript">const driver = new Driver(); |
|
|
// Define the steps for introduction |
|
|
driver.defineSteps([ |
|
|
{ |
|
|
element: '#first-element-introduction', |
|
|
popover: { |
|
|
title: 'Title on Popover', |
|
|
description: 'Body of the popover', |
|
|
position: 'left' |
|
|
} |
|
|
}, |
|
|
{ |
|
|
element: '#second-element-introduction', |
|
|
popover: { |
|
|
title: 'Title on Popover', |
|
|
description: 'Body of the popover', |
|
|
position: 'top' |
|
|
} |
|
|
}, |
|
|
{ |
|
|
element: '#third-element-introduction', |
|
|
popover: { |
|
|
title: 'Title on Popover', |
|
|
description: 'Body of the popover', |
|
|
position: 'right' |
|
|
} |
|
|
}, |
|
|
]); |
|
|
// Start the introduction |
|
|
driver.start(); |
|
|
</code></pre> |
|
|
<p class="top-20">This is just a quick example for the feature introduction. For a richer one, please have a look at |
|
|
the |
|
|
<a href="#" class="btn__example">"Quick Tour"</a></p> |
|
|
|
|
|
<p>You may also turn off the footer buttons in popover, in which case user can control the popover using the arrows |
|
|
keys on keyboard. Or you may control it using the methods provided by Driver.</p> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div id="element-without-popover" class="section__example"> |
|
|
<h4>Without Overlay</h4> |
|
|
<p>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`.</p> |
|
|
<a href="#" class="btn__run-demo" id="run-element-without-popover">Show Demo</a> |
|
|
<pre><code class="javascript">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` |
|
|
} |
|
|
}); |
|
|
</code></pre> |
|
|
<p class="top-20">..and you can do the same for the feature introductions</p> |
|
|
</div> |
|
|
|
|
|
<hr class="hr__fancy"> |
|
|
|
|
|
<div class="section__example"> |
|
|
<div id="api_section"> |
|
|
<h3>..and much much more</h3> |
|
|
<p>Driver comes with many options that you can manipulate to make driver behave as you may like</p> |
|
|
</div> |
|
|
<h4>Driver Definition</h4> |
|
|
<p>Here are the options that Driver understands</p> |
|
|
<pre><code class="javascript">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 |
|
|
}); |
|
|
</code></pre> |
|
|
</div> |
|
|
<div class="section__example"> |
|
|
<h4>Step Definition</h4> |
|
|
<p>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 <code>highlight</code> method</p> |
|
|
<pre><code class="javascript">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 |
|
|
} |
|
|
}; |
|
|
</code></pre> |
|
|
</div> |
|
|
<div class="section__example"> |
|
|
<h4>API Methods</h4> |
|
|
<p>Below are the set of methods that are available to you</p> |
|
|
<pre><code class="javascript">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 |
|
|
</code></pre> |
|
|
</div> |
|
|
<p class="top-20">You can use a variety of options to achieve whatever you may want. I have some plans on improving |
|
|
it further, make sure to keep an eye on the <a href="https://github.com/kamranahmedse/driver.js" target="_blank">github |
|
|
page</a></p> |
|
|
</section> |
|
|
<hr class="hr__fancy"> |
|
|
<div class="section__example"> |
|
|
<h4>Contributing</h4> |
|
|
<p>You can find the contribution instructions on the <a href="https://github.com/kamranahmedse/driver.js" |
|
|
target="_blank">github page</a>. Feel free to submit an |
|
|
issue, create a pull request or spread the word</p> |
|
|
</div> |
|
|
<hr class="hr__fancy"> |
|
|
<div class="section__example"> |
|
|
<p>A product by <a href="http://twitter.com/kamranahmedse" target="_blank">Kamran</a> produced out of boredom and |
|
|
frustration in cold Berlin after he gave up on trying to find a perfect solution to integrate journey introduction |
|
|
and overlays.</p> |
|
|
<a href="https://twitter.com/kamranahmedse?ref_src=twsrc%5Etfw" |
|
|
class="twitter-follow-button mr-3" |
|
|
data-show-screen-name="false" |
|
|
data-size="large" |
|
|
target="_blank" |
|
|
data-show-count="true">Follow @kamranahmedse</a> |
|
|
|
|
|
<a class="github-button" href="https://github.com/kamranahmedse" |
|
|
data-size="large" |
|
|
target="_blank" |
|
|
data-show-count="true" |
|
|
aria-label="Follow @kamranahmedse on GitHub">Follow</a> |
|
|
</div> |
|
|
</div> |
|
|
|
|
|
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> |
|
|
<script async defer src="//buttons.github.io/buttons.js"></script> |
|
|
<script src="//twemoji.maxcdn.com/2/twemoji.min.js?2.5"></script> |
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script> |
|
|
|
|
|
<script src="./dist/driver.js"></script> |
|
|
<script src="./dist/demo.js"></script> |
|
|
<script src="./dist/emoji.js"></script> |
|
|
</body> |
|
|
</html> |
