Vicky C Lau
commited on
Commit
Β·
32ebc11
1
Parent(s):
586b47c
Edited grammar for correctness and clarity (#38)
Browse files
readme.md
CHANGED
@@ -35,20 +35,20 @@ For Usage and Examples, [have a look at demo](http://kamranahmed.info/driver)
|
|
35 |
|
36 |
## So, yet another tour library?
|
37 |
|
38 |
-
**No
|
39 |
|
40 |
-
Driver.js is written in Vanilla JS, has zero dependencies and is highly customizable. It has several options allowing you to manipulate how it behaves and also **provides you the hooks** to manipulate the elements as they are highlighted about to be highlighted or deselected.
|
41 |
|
42 |
## Installation
|
43 |
|
44 |
-
You can install it using `yarn` or `npm`, whatever you prefer
|
45 |
|
46 |
```sh
|
47 |
yarn add driver.js
|
48 |
npm install driver.js
|
49 |
```
|
50 |
|
51 |
-
Or grab the code from `dist` directory and include it directly
|
52 |
|
53 |
```html
|
54 |
<link rel="stylesheet" href="/dist/driver.min.css">
|
@@ -59,21 +59,21 @@ Or grab the code from `dist` directory and include it directly
|
|
59 |
|
60 |
## Usage and Demo
|
61 |
|
62 |
-
Demos and many more usage examples can be found [
|
63 |
|
64 |
### Highlighting Single Element β [Demo](http://kamranahmed.info/driver#single-element-no-popover)
|
65 |
|
66 |
-
|
67 |
|
68 |
```javascript
|
69 |
const driver = new Driver();
|
70 |
driver.highlight('#create-post');
|
71 |
```
|
72 |
-
A real world usage example for this
|
73 |
|
74 |
### Highlight and Popover β [Demo](http://kamranahmed.info/driver#single-element-with-popover)
|
75 |
|
76 |
-
You can show additional details beside the highlighted element using the popover
|
77 |
|
78 |
```javascript
|
79 |
const driver = new Driver();
|
@@ -90,7 +90,7 @@ Also, `title` and `description` can have HTML as well.
|
|
90 |
|
91 |
### Positioning the Popover β [Demo](http://kamranahmed.info/driver#single-element-with-popover-position)
|
92 |
|
93 |
-
By default, driver automatically finds the suitable position for the popover and displays it
|
94 |
|
95 |
```javascript
|
96 |
const driver = new Driver();
|
@@ -106,7 +106,7 @@ driver.highlight({
|
|
106 |
|
107 |
### Creating Feature Introductions β [Demo](http://kamranahmed.info/driver)
|
108 |
|
109 |
-
Feature introductions are helpful
|
110 |
|
111 |
```javascript
|
112 |
const driver = new Driver();
|
@@ -142,17 +142,17 @@ driver.defineSteps([
|
|
142 |
// Start the introduction
|
143 |
driver.start();
|
144 |
```
|
145 |
-
You can also hide the buttons and control the introductions programmatically by using the API methods listed below
|
146 |
|
147 |

|
148 |
|
149 |
## API
|
150 |
|
151 |
-
Driver comes with several options that you can manipulate to make driver behave as you
|
152 |
|
153 |
### Driver Definition
|
154 |
|
155 |
-
Here are the options that Driver understands
|
156 |
|
157 |
```javascript
|
158 |
const driver = new Driver({
|
@@ -176,7 +176,7 @@ Note that all the button options that you provide in the driver definition can b
|
|
176 |
|
177 |
### Step Definition
|
178 |
|
179 |
-
Here are the set of options that you can pass while defining steps `defineSteps` or the object that you pass to `highlight` method
|
180 |
|
181 |
```javascript
|
182 |
const stepDefinition = {
|
@@ -194,14 +194,14 @@ const stepDefinition = {
|
|
194 |
};
|
195 |
```
|
196 |
|
197 |
-
For example, here is how it would look when highlighting a single element
|
198 |
|
199 |
```javascript
|
200 |
const driver = new Driver(driverOptions);
|
201 |
driver.highlight(stepDefinition);
|
202 |
```
|
203 |
|
204 |
-
And this is how it would look when creating a step by step guide
|
205 |
|
206 |
```javascript
|
207 |
const driver = new Driver(driverOptions);
|
@@ -215,7 +215,7 @@ driver.defineSteps([
|
|
215 |
|
216 |
### API Methods
|
217 |
|
218 |
-
Below are the set of methods that are available
|
219 |
|
220 |
```javascript
|
221 |
const driver = new Driver(driverOptions);
|
@@ -263,7 +263,7 @@ activeElement.showPopover(); // Show the popover
|
|
263 |
activeElement.getNode(); // Gets the DOM Element behind this element
|
264 |
```
|
265 |
|
266 |
-
**Note β** Do not forget to add `e.stopPropagation()` to the `click` binding that triggers driver
|
267 |
|
268 |

|
269 |
|
@@ -281,11 +281,11 @@ activeElement.getNode(); // Gets the DOM Element behind this element
|
|
281 |
|
282 |
## Contributions
|
283 |
|
284 |
-
Feel free to submit pull requests, create issues or spread the word
|
285 |
|
286 |
## Sponsored By
|
287 |
|
288 |
-
Thanks to [BrowserStack](https://browserstack.com) for sponsoring the compatibility testing needs
|
289 |
|
290 |
[](https://www.browserstack.com)
|
291 |
|
|
|
35 |
|
36 |
## So, yet another tour library?
|
37 |
|
38 |
+
**No**, it is not. **Tours are just one of the many use-cases**. Driver.js can be used wherever you need some sort of overlay for the page; some common usecases could be: e.g. dimming the background when user is interacting with some component i.e. [the way Facebook does](https://i.imgur.com/Q3PzaKk.png) when you try to create a post, using it as a focus shifter to bring user's attention to some component on page, or using it to simulate those "Turn off the Lights" widgets that you might have seen on video players online, etc.
|
39 |
|
40 |
+
Driver.js is written in Vanilla JS, has zero dependencies and is highly customizable. It has several options allowing you to manipulate how it behaves and also **provides you the hooks** to manipulate the elements as they are highlighted, about to be highlighted, or deselected.
|
41 |
|
42 |
## Installation
|
43 |
|
44 |
+
You can install it using `yarn` or `npm`, whatever you prefer.
|
45 |
|
46 |
```sh
|
47 |
yarn add driver.js
|
48 |
npm install driver.js
|
49 |
```
|
50 |
|
51 |
+
Or grab the code from `dist` directory and include it directly.
|
52 |
|
53 |
```html
|
54 |
<link rel="stylesheet" href="/dist/driver.min.css">
|
|
|
59 |
|
60 |
## Usage and Demo
|
61 |
|
62 |
+
Demos and many more usage examples can be found [in the docs page](http://kamranahmed.info/driver).
|
63 |
|
64 |
### Highlighting Single Element β [Demo](http://kamranahmed.info/driver#single-element-no-popover)
|
65 |
|
66 |
+
You can highlight a single element by simply passing the selector.
|
67 |
|
68 |
```javascript
|
69 |
const driver = new Driver();
|
70 |
driver.highlight('#create-post');
|
71 |
```
|
72 |
+
A real world usage example for this is: using it to dim the background and highlight the required element e.g. the way facebook does it when creating a post.
|
73 |
|
74 |
### Highlight and Popover β [Demo](http://kamranahmed.info/driver#single-element-with-popover)
|
75 |
|
76 |
+
You can show additional details beside the highlighted element using the popover.
|
77 |
|
78 |
```javascript
|
79 |
const driver = new Driver();
|
|
|
90 |
|
91 |
### Positioning the Popover β [Demo](http://kamranahmed.info/driver#single-element-with-popover-position)
|
92 |
|
93 |
+
By default, driver automatically finds the suitable position for the popover and displays it. You can override it using `position` property.
|
94 |
|
95 |
```javascript
|
96 |
const driver = new Driver();
|
|
|
106 |
|
107 |
### Creating Feature Introductions β [Demo](http://kamranahmed.info/driver)
|
108 |
|
109 |
+
Feature introductions are helpful when 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 the keyboard or using the buttons on popovers.
|
110 |
|
111 |
```javascript
|
112 |
const driver = new Driver();
|
|
|
142 |
// Start the introduction
|
143 |
driver.start();
|
144 |
```
|
145 |
+
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
|
146 |
|
147 |

|
148 |
|
149 |
## API
|
150 |
|
151 |
+
Driver comes with several options that you can manipulate to make driver behave as you like
|
152 |
|
153 |
### Driver Definition
|
154 |
|
155 |
+
Here are the options that Driver understands:
|
156 |
|
157 |
```javascript
|
158 |
const driver = new Driver({
|
|
|
176 |
|
177 |
### Step Definition
|
178 |
|
179 |
+
Here are the set of options that you can pass while defining steps `defineSteps` or the object that you pass to `highlight` method:
|
180 |
|
181 |
```javascript
|
182 |
const stepDefinition = {
|
|
|
194 |
};
|
195 |
```
|
196 |
|
197 |
+
For example, here is how it would look when highlighting a single element:
|
198 |
|
199 |
```javascript
|
200 |
const driver = new Driver(driverOptions);
|
201 |
driver.highlight(stepDefinition);
|
202 |
```
|
203 |
|
204 |
+
And this is how it would look when creating a step by step guide:
|
205 |
|
206 |
```javascript
|
207 |
const driver = new Driver(driverOptions);
|
|
|
215 |
|
216 |
### API Methods
|
217 |
|
218 |
+
Below are the set of methods that are available:
|
219 |
|
220 |
```javascript
|
221 |
const driver = new Driver(driverOptions);
|
|
|
263 |
activeElement.getNode(); // Gets the DOM Element behind this element
|
264 |
```
|
265 |
|
266 |
+
**Note β** Do not forget to add `e.stopPropagation()` to the `click` binding that triggers driver.
|
267 |
|
268 |

|
269 |
|
|
|
281 |
|
282 |
## Contributions
|
283 |
|
284 |
+
Feel free to submit pull requests, create issues or spread the word.
|
285 |
|
286 |
## Sponsored By
|
287 |
|
288 |
+
Thanks to [BrowserStack](https://browserstack.com) for sponsoring the compatibility testing needs.
|
289 |
|
290 |
[](https://www.browserstack.com)
|
291 |
|