kamrify commited on
Commit
5697c7f
·
1 Parent(s): e545e81

Update readme

Browse files
docs/src/content/guides/installation.mdx CHANGED
@@ -28,7 +28,7 @@ Alternatively, you can use CDN and include the script in your HTML file:
28
  Once installed, you can import the package in your project. The following example shows how to highlight an element:
29
 
30
  ```js
31
- import driver from "driver.js";
32
  import "driver.js/dist/driver.css";
33
 
34
  const driverObj = driver();
 
28
  Once installed, you can import the package in your project. The following example shows how to highlight an element:
29
 
30
  ```js
31
+ import { driver } from "driver.js";
32
  import "driver.js/dist/driver.css";
33
 
34
  const driverObj = driver();
readme.md CHANGED
@@ -1,4 +1,4 @@
1
- <h1 align="center"><img height="150" src="./.github/images/driver.svg" /><br> Driver.js</h1>
2
 
3
  <p align="center">
4
  <a href="https://github.com/kamranahmedse/driver.js/blob/master/license">
@@ -25,365 +25,28 @@
25
  - **Feature introductions**: create powerful feature introductions for your web applications
26
  - **Focus shifters**: add focus shifters for users
27
  - **User friendly**: Everything is controllable by keyboard
28
- - **Consistent behavior**: usable across all browsers (including in-famous IE)
 
29
  - **MIT Licensed**: free for personal and commercial use
30
 
31
- ![](./demo/images/split.png)
32
-
33
- For Usage and Examples, [have a look at demo](http://kamranahmed.info/driver.js)
34
 
35
  ## So, yet another tour library?
36
 
37
- **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/Q3PzaKkr.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.
38
-
39
- 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.
40
-
41
- ## Installation
42
-
43
- You can install it using `yarn` or `npm`, whatever you prefer.
44
-
45
- ```bash
46
- yarn add driver.js
47
- npm install driver.js
48
- ```
49
-
50
- Or include it using CDN. If you want a specific version, put it as `[email protected]` in the name
51
-
52
- ```html
53
- <script src="https://unpkg.com/driver.js/dist/driver.min.js"></script>
54
- <link rel="stylesheet" href="https://unpkg.com/driver.js/dist/driver.min.css" />
55
- ```
56
-
57
- Or grab the code from `dist` directory and include it directly.
58
-
59
- ```html
60
- <link rel="stylesheet" href="/dist/driver.min.css" />
61
- <script src="/dist/driver.min.js"></script>
62
- ```
63
-
64
- ![](./demo/images/split.png)
65
-
66
- ## Usage and Demo
67
-
68
- If you are using some sort of module bundler, import the library and the CSS file
69
-
70
- ```javascript
71
- import Driver from "driver.js";
72
- import "driver.js/dist/driver.min.css";
73
- ```
74
-
75
- otherwise use the `script` and `link` tags to import the JavaScript and CSS files.
76
-
77
- Demos and many more usage examples can be found [in the docs page](http://kamranahmed.info/driver.js).
78
-
79
- ### Highlighting Single Element – [Demo](http://kamranahmed.info/driver.js#single-element-no-popover)
80
-
81
- You can highlight a single element by simply passing the selector.
82
-
83
- ```javascript
84
- const driver = new Driver();
85
- driver.highlight("#create-post");
86
- ```
87
-
88
- 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.
89
-
90
- ### Highlight and Popover – [Demo](http://kamranahmed.info/driver.js#single-element-with-popover)
91
-
92
- You can show additional details beside the highlighted element using the popover.
93
-
94
- ```javascript
95
- const driver = new Driver();
96
- driver.highlight({
97
- element: "#some-element",
98
- popover: {
99
- title: "Title for the Popover",
100
- description: "Description for it",
101
- },
102
- });
103
- ```
104
-
105
- Also, `title` and `description` can have HTML as well.
106
-
107
- ### Positioning the Popover – [Demo](http://kamranahmed.info/driver.js#single-element-with-popover-position)
108
-
109
- By default, driver automatically finds the suitable position for the popover and displays it. You can override it using `position` property.
110
-
111
- ```javascript
112
- const driver = new Driver();
113
- driver.highlight({
114
- element: "#some-element",
115
- popover: {
116
- title: "Title for the Popover",
117
- description: "Description for it",
118
- // position can be left, left-center, left-bottom, top,
119
- // top-center, top-right, right, right-center, right-bottom,
120
- // bottom, bottom-center, bottom-right, mid-center
121
- position: "left",
122
- },
123
- });
124
- ```
125
-
126
- You can also add offset to the popover position by using the `offset` property
127
-
128
- ```javascript
129
- const driver = new Driver();
130
- driver.highlight({
131
- element: "#some-element",
132
- popover: {
133
- title: "Title for the Popover",
134
- description: "Description for it",
135
- position: "bottom",
136
- // Will show it 20 pixels away from the actual position of popover
137
- // You may also provide the negative values
138
- offset: 20,
139
- },
140
- });
141
- ```
142
-
143
- ### Creating Feature Introductions – [Demo](http://kamranahmed.info/driver.js)
144
-
145
- Feature introductions are helpful when onboarding new users and giving them an idea about different parts of the application; you can create them seamlessly 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.
146
-
147
- ```javascript
148
- const driver = new Driver();
149
-
150
- // Define the steps for introduction
151
- driver.defineSteps([
152
- {
153
- element: "#first-element-introduction",
154
- popover: {
155
- className: "first-step-popover-class",
156
- title: "Title on Popover",
157
- description: "Body of the popover",
158
- position: "left",
159
- },
160
- },
161
- {
162
- element: "#second-element-introduction",
163
- popover: {
164
- title: "Title on Popover",
165
- description: "Body of the popover",
166
- position: "top",
167
- },
168
- },
169
- {
170
- element: "#third-element-introduction",
171
- popover: {
172
- title: "Title on Popover",
173
- description: "Body of the popover",
174
- position: "right",
175
- },
176
- },
177
- ]);
178
-
179
- // Start the introduction
180
- driver.start();
181
- ```
182
-
183
- You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
184
-
185
- ![](./demo/images/split.png)
186
-
187
- ### Asynchronous Actions – [Demo](http://kamranahmed.info/driver.js)
188
-
189
- For any asynchronous actions between the transition steps, you may delay the execution till the action completes. All you have to do is stop the transition using `driver.preventMove()` in your `onNext` or `onPrevious` callbacks and initiate it manually using `driver.moveNext()`. Here is a sample implementation where it will stop at the second step for four seconds and then move on to the next step.
190
 
191
- ```javascript
192
- const driver = new Driver();
193
 
194
- // Define the steps for introduction
195
- driver.defineSteps([
196
- {
197
- element: "#first-element-introduction",
198
- popover: {
199
- title: "Title on Popover",
200
- description: "Body of the popover",
201
- position: "left",
202
- },
203
- },
204
- {
205
- element: "#second-element-introduction",
206
- popover: {
207
- title: "Title on Popover",
208
- description: "Body of the popover",
209
- position: "top",
210
- },
211
- onNext: () => {
212
- // Prevent moving to the next step
213
- driver.preventMove();
214
 
215
- // Perform some action or create the element to move to
216
- // And then move to that element
217
- setTimeout(() => {
218
- driver.moveNext();
219
- }, 4000);
220
- },
221
- },
222
- {
223
- element: "#third-element-introduction",
224
- popover: {
225
- title: "Title on Popover",
226
- description: "Body of the popover",
227
- position: "right",
228
- },
229
- },
230
- ]);
231
 
232
- // Start the introduction
233
- driver.start();
234
- ```
235
-
236
- You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
237
-
238
- ![](./demo/images/split.png)
239
-
240
- ## API
241
-
242
- Driver comes with several options that you can manipulate to make Driver behave as you like
243
-
244
- ### Driver Definition
245
-
246
- Here are the options that Driver understands:
247
-
248
- ```javascript
249
- const driver = new Driver({
250
- className: "scoped-class", // className to wrap driver.js popover
251
- animate: true, // Whether to animate or not
252
- opacity: 0.75, // Background opacity (0 means only popovers and without overlay)
253
- padding: 10, // Distance of element from around the edges
254
- allowClose: true, // Whether the click on overlay should close or not
255
- overlayClickNext: false, // Whether the click on overlay should move next
256
- doneBtnText: "Done", // Text on the final button
257
- closeBtnText: "Close", // Text on the close button for this step
258
- stageBackground: "#ffffff", // Background color for the staged behind highlighted element
259
- nextBtnText: "Next", // Next button text for this step
260
- prevBtnText: "Previous", // Previous button text for this step
261
- showButtons: false, // Do not show control buttons in footer
262
- keyboardControl: true, // Allow controlling through keyboard (escape to close, arrow keys to move)
263
- scrollIntoViewOptions: {}, // We use `scrollIntoView()` when possible, pass here the options for it if you want any
264
- onHighlightStarted: Element => {}, // Called when element is about to be highlighted
265
- onHighlighted: Element => {}, // Called when element is fully highlighted
266
- onDeselected: Element => {}, // Called when element has been deselected
267
- onReset: Element => {}, // Called when overlay is about to be cleared
268
- onNext: Element => {}, // Called when moving to next step on any step
269
- onPrevious: Element => {}, // Called when moving to previous step on any step
270
- });
271
- ```
272
-
273
- Note that all the button options that you provide in the driver definition can be overridden for a specific step by giving them in the step definition
274
-
275
- ### Step Definition
276
-
277
- Here are the set of options that you can pass while defining steps `defineSteps` or the object that you pass to `highlight` method:
278
-
279
- ```javascript
280
- const stepDefinition = {
281
- element: "#some-item", // Query selector string or Node to be highlighted
282
- stageBackground: "#ffffff", // This will override the one set in driver
283
- popover: {
284
- // There will be no popover if empty or not given
285
- className: "popover-class", // className to wrap this specific step popover in addition to the general className in Driver options
286
- title: "Title", // Title on the popover
287
- description: "Description", // Body of the popover
288
- showButtons: false, // Do not show control buttons in footer
289
- doneBtnText: "Done", // Text on the last button
290
- closeBtnText: "Close", // Text on the close button
291
- nextBtnText: "Next", // Next button text
292
- prevBtnText: "Previous", // Previous button text
293
- },
294
- onNext: () => {}, // Called when moving to next step from current step
295
- onPrevious: () => {}, // Called when moving to previous step from current step
296
- };
297
- ```
298
-
299
- For example, here is how it would look when highlighting a single element:
300
-
301
- ```javascript
302
- const driver = new Driver(driverOptions);
303
- driver.highlight(stepDefinition);
304
- ```
305
-
306
- And this is how it would look when creating a step by step guide:
307
-
308
- ```javascript
309
- const driver = new Driver(driverOptions);
310
- driver.defineSteps([stepDefinition1, stepDefinition2, stepDefinition3, stepDefinition4]);
311
- ```
312
-
313
- ### API Methods
314
-
315
- Below are the set of methods that are available:
316
-
317
- ```javascript
318
- const driver = new Driver(driverOptions);
319
-
320
- // Checks if the driver is active or not
321
- if (driver.isActivated) {
322
- console.log("Driver is active");
323
- }
324
-
325
- // In case of the steps guide, you can call below methods
326
- driver.defineSteps([stepDefinition1, stepDefinition2, stepDefinition3]);
327
- driver.start((stepNumber = 0)); // Starts driving through the defined steps
328
- driver.moveNext(); // Moves to next step in the steps list
329
- driver.movePrevious(); // Moves to previous step in the steps list
330
- driver.hasNextStep(); // Checks if there is next step to move to
331
- driver.hasPreviousStep(); // Checks if there is previous step to move to
332
-
333
- // Prevents the current move. Useful in `onNext` or `onPrevious` if you want to
334
- // perform some asynchronous task and manually move to next step
335
- driver.preventMove();
336
-
337
- // Highlights the element using query selector or the step definition
338
- driver.highlight(string | stepDefinition);
339
-
340
- // Reposition the popover and highlighted element
341
- driver.refresh();
342
-
343
- // Resets the overlay and clears the screen
344
- driver.reset();
345
-
346
- // Additionally you can pass a boolean parameter
347
- // to clear immediately and not do the animations etc
348
- // Could be useful when you, let's say, want to run
349
- // a different instance of driver while one was running
350
- driver.reset((clearImmediately = false));
351
-
352
- // Checks if there is any highlighted element
353
- if (driver.hasHighlightedElement()) {
354
- console.log("There is an element highlighted");
355
- }
356
-
357
- // Gets the currently highlighted element on screen
358
- // It would be an instance of `/src/core/element.js`
359
- const activeElement = driver.getHighlightedElement();
360
-
361
- // Gets the last highlighted element, would be an instance of `/src/core/element.js`
362
- const lastActiveElement = driver.getLastHighlightedElement();
363
-
364
- activeElement.getCalculatedPosition(); // Gets screen co-ordinates of the active element
365
- activeElement.hidePopover(); // Hide the popover
366
- activeElement.showPopover(); // Show the popover
367
-
368
- activeElement.getNode(); // Gets the DOM Element behind this element
369
- ```
370
-
371
- ![](./demo/images/split.png)
372
-
373
- **Note –** Do not forget to add `e.stopPropagation()` to the `click` binding that triggers driver.
374
-
375
- ![](./demo/images/split.png)
376
 
377
  ## Contributions
378
 
379
  Feel free to submit pull requests, create issues or spread the word.
380
 
381
- ## Sponsored By
382
-
383
- Thanks to [BrowserStack](https://browserstack.com) for sponsoring the compatibility testing needs.
384
-
385
- [![BrowserStack](./demo/images/browserstack.png)](https://www.browserstack.com)
386
-
387
  ## License
388
 
389
  MIT &copy; [Kamran Ahmed](https://twitter.com/kamranahmedse)
 
1
+ <h1 align="center"><img height="150" src="https://driverjs.com/driver.svg" /><br> Driver.js</h1>
2
 
3
  <p align="center">
4
  <a href="https://github.com/kamranahmedse/driver.js/blob/master/license">
 
25
  - **Feature introductions**: create powerful feature introductions for your web applications
26
  - **Focus shifters**: add focus shifters for users
27
  - **User friendly**: Everything is controllable by keyboard
28
+ - **TypeScript**: Written in TypeScript
29
+ - **Consistent behavior**: usable across all browsers
30
  - **MIT Licensed**: free for personal and commercial use
31
 
32
+ For Usage and Examples, [have a look at demo](https://driverjs.com)
 
 
33
 
34
  ## So, yet another tour library?
35
 
36
+ **No**, it's more than a tour library. **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: [highlighting a page component](https://i.imgur.com/TS0LSK9.png) when user is interacting with some component to keep them focused, providing contextual help e.g. popover with dimmed background when user is filling a form, using it as a focus shifter to bring user's attention to some component on page, using it to simulate those "Turn off the Lights" widgets that you might have seen on video players online, usage as a simple modal, and of-course product tours etc.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
37
 
38
+ Driver.js is written in Vanilla TypeScript, has zero dependencies and is highly customizable. It has several options allowing you to change how it behaves and also **provides you the hooks** to manipulate the elements as they are highlighted, about to be highlighted, or deselected.
 
39
 
40
+ > Also, comparing the size of Driver.js with other libraries, since it doesn't have any dependencies, it is **just ~5kb gzipped** while others are 12kb+.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
41
 
42
+ ## Demos and Usage
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
43
 
44
+ For complete documentation, visit [driverjs.com](https://driverjs.com)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
45
 
46
  ## Contributions
47
 
48
  Feel free to submit pull requests, create issues or spread the word.
49
 
 
 
 
 
 
 
50
  ## License
51
 
52
  MIT &copy; [Kamran Ahmed](https://twitter.com/kamranahmedse)