Update readme
Browse files
readme.md
CHANGED
@@ -1,8 +1,11 @@
|
|
1 |
<h1 align="center"><img src="./demo/images/driver.png" /><br> Driver.js</h1>
|
2 |
|
3 |
<p align="center">
|
4 |
-
<a href="https://
|
5 |
-
<img src="https://img.shields.io/
|
|
|
|
|
|
|
6 |
</a>
|
7 |
<a href="http://makeapullrequest.com">
|
8 |
<img src="https://img.shields.io/badge/contributions-welcome-green.svg" />
|
@@ -23,7 +26,7 @@
|
|
23 |
* **Light-weight**: ~4kb in size, vanilla JavaScript and no external dependency
|
24 |
* **Highly customizable**: has a powerful API and can be used however you want
|
25 |
* **Highlight anything**: highlight any (literally any) element on page
|
26 |
-
* **Feature introductions**: create powerful feature introductions
|
27 |
* **Focus shifters**: add focus shifters for users
|
28 |
* **User friendly**: Everything is controllable by keyboard
|
29 |
* **Consistent behavior**: usable across all browsers (including in-famous IE)
|
@@ -65,7 +68,9 @@ driver.highlight('#create-post');
|
|
65 |
```
|
66 |
A real world usage example for this could be using it to dim the background and highlight the required element e.g. the way facebook does it on creating a post.
|
67 |
|
68 |
-
|
|
|
|
|
69 |
|
70 |
You can show additional details beside the highlighted element using the popover
|
71 |
|
@@ -82,6 +87,8 @@ driver.highlight({
|
|
82 |
|
83 |
Also, `title` and `description` can have HTML as well.
|
84 |
|
|
|
|
|
85 |
### Positioning the Popover – [Demo](http://kamranahmed.info/driver#single-element-with-popover-position)
|
86 |
|
87 |
By default, driver automatically finds the suitable position for the popover and displays it, you can override it using `position` property
|
@@ -98,9 +105,11 @@ driver.highlight({
|
|
98 |
});
|
99 |
```
|
100 |
|
|
|
|
|
101 |
### Creating Feature Introductions – [Demo](http://kamranahmed.info/driver)
|
102 |
|
103 |
-
Feature introductions are helpful in onboarding new users and giving them idea about different parts of the application, you can create them seemlessly with driver. Define the steps and call the `start` when you want to start presenting
|
104 |
|
105 |
```javascript
|
106 |
const driver = new Driver();
|
@@ -136,4 +145,79 @@ driver.defineSteps([
|
|
136 |
// Start the introduction
|
137 |
driver.start();
|
138 |
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
139 |
|
|
|
1 |
<h1 align="center"><img src="./demo/images/driver.png" /><br> Driver.js</h1>
|
2 |
|
3 |
<p align="center">
|
4 |
+
<a href="https://github.com/kamranahmedse/driver.js/blob/master/license">
|
5 |
+
<img src="https://img.shields.io/github/license/kamranahmedse/driver.js.svg" />
|
6 |
+
</a>
|
7 |
+
<a href="https://npmjs.org/package/driver.js">
|
8 |
+
<img src="https://img.shields.io/npm/v/driver.js.svg" alt="version" />
|
9 |
</a>
|
10 |
<a href="http://makeapullrequest.com">
|
11 |
<img src="https://img.shields.io/badge/contributions-welcome-green.svg" />
|
|
|
26 |
* **Light-weight**: ~4kb in size, vanilla JavaScript and no external dependency
|
27 |
* **Highly customizable**: has a powerful API and can be used however you want
|
28 |
* **Highlight anything**: highlight any (literally any) element on page
|
29 |
+
* **Feature introductions**: create powerful feature introductions for your web applications
|
30 |
* **Focus shifters**: add focus shifters for users
|
31 |
* **User friendly**: Everything is controllable by keyboard
|
32 |
* **Consistent behavior**: usable across all browsers (including in-famous IE)
|
|
|
68 |
```
|
69 |
A real world usage example for this could be using it to dim the background and highlight the required element e.g. the way facebook does it on creating a post.
|
70 |
|
71 |
+

|
72 |
+
|
73 |
+
### Highlight and Popover – [Demo](http://kamranahmed.info/driver#single-element-with-popover)
|
74 |
|
75 |
You can show additional details beside the highlighted element using the popover
|
76 |
|
|
|
87 |
|
88 |
Also, `title` and `description` can have HTML as well.
|
89 |
|
90 |
+

|
91 |
+
|
92 |
### Positioning the Popover – [Demo](http://kamranahmed.info/driver#single-element-with-popover-position)
|
93 |
|
94 |
By default, driver automatically finds the suitable position for the popover and displays it, you can override it using `position` property
|
|
|
105 |
});
|
106 |
```
|
107 |
|
108 |
+

|
109 |
+
|
110 |
### Creating Feature Introductions – [Demo](http://kamranahmed.info/driver)
|
111 |
|
112 |
+
Feature introductions are helpful in onboarding new users and giving them idea about different parts of the application, you can create them seemlessly with driver. Define the steps and call the `start` when you want to start presenting. User will be able to control the steps using keyboard or using the buttons on popovers.
|
113 |
|
114 |
```javascript
|
115 |
const driver = new Driver();
|
|
|
145 |
// Start the introduction
|
146 |
driver.start();
|
147 |
```
|
148 |
+
You can also hide the buttons and control the introductions programmatically by using the API methods listed below
|
149 |
+
|
150 |
+

|
151 |
+
|
152 |
+
# API
|
153 |
+
|
154 |
+
Driver comes with several options that you can manipulate to make driver behave as you may like
|
155 |
+
|
156 |
+
### Driver Definition
|
157 |
+
|
158 |
+
Here are the options that Driver understands
|
159 |
+
|
160 |
+
```javascript
|
161 |
+
const driver = new Driver({
|
162 |
+
animate: true, // Animate while changing highlighted element
|
163 |
+
opacity: 0.75, // Background opacity (0 means only popovers and without overlay)
|
164 |
+
padding: 10, // Distance of element from around the edges
|
165 |
+
onHighlightStarted: (Element) {}, // Called when element is about to be highlighted
|
166 |
+
onHighlighted: (Element) {}, // Called when element is fully highlighted
|
167 |
+
onDeselected: (Element) {}, // Called when element has been deselected
|
168 |
+
});
|
169 |
+
```
|
170 |
+
|
171 |
+
### Step Definition
|
172 |
+
|
173 |
+
Here are the set of options that you can pass while defining steps `defineSteps` or the object that you pass to `highlight` method
|
174 |
+
|
175 |
+
```javascript
|
176 |
+
const stepDefinition = {
|
177 |
+
element: '#some-item', // Query selector for the item to be highlighted
|
178 |
+
popover: { // There will be no popover if empty or not given
|
179 |
+
title: 'Title', // Title on the popover
|
180 |
+
description: 'Description', // Body of the popover
|
181 |
+
showButtons: false, // Do not show control buttons in footer
|
182 |
+
doneBtnText: 'Done', // Text on the last button
|
183 |
+
closeBtnText: 'Close', // Text on the close button
|
184 |
+
nextBtnText: 'Next', // Next button text
|
185 |
+
prevBtnText: 'Previous', // Previous button text
|
186 |
+
}
|
187 |
+
};
|
188 |
+
```
|
189 |
+
|
190 |
+
### API Methods
|
191 |
+
|
192 |
+
Below are the set of methods that are available to you
|
193 |
+
|
194 |
+
```javascript
|
195 |
+
const driver = new Driver(driverOptions);
|
196 |
+
|
197 |
+
const isActivated = driver.isActivated; // Checks if the driver is active or not
|
198 |
+
driver.moveNext(); // Moves to next step in the steps list
|
199 |
+
driver.movePrevious(); // Moves to previous step in the steps list
|
200 |
+
driver.start(stepNumber = 0); // Starts driving through the defined steps
|
201 |
+
driver.highlight(string|stepDefinition); // highlights the element using query selector or the step definition
|
202 |
+
driver.reset(); // Resets the overlay and clears the screen
|
203 |
+
driver.hasHighlightedElement(); // Checks if there is any highlighted element
|
204 |
+
driver.hasNextStep(); // Checks if there is next step to move to
|
205 |
+
driver.hasPreviousStep(); // Checks if there is previous step to move to
|
206 |
+
|
207 |
+
// Gets the currently highlighted element on screen
|
208 |
+
const activeElement = driver.getHighlightedElement();
|
209 |
+
const lastActiveElement = driver.getLastHighlightedElement();
|
210 |
+
activeElement.getScreenCoordinates(); // Gets screen co-ordinates of the active element
|
211 |
+
activeElement.hidePopover(); // Hide the popover
|
212 |
+
activeElement.showPopover(); // Show the popover
|
213 |
+
|
214 |
+
activeElement.getNode(); // Gets the DOM Element behind this element
|
215 |
+
```
|
216 |
+
|
217 |
+

|
218 |
+
|
219 |
+
## License
|
220 |
+
|
221 |
+
MIT © [Kamran Ahmed](https://twitter.com/kamranahmedse)
|
222 |
+
|
223 |
|