mirror of
https://github.com/kamranahmedse/driver.js.git
synced 2026-10-31 03:52:13 +08:00
Add API configuration page
This commit is contained in:
Kamran Ahmed
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "API Reference"
|
||||
groupTitle: "Introduction"
|
||||
sort: 4
|
||||
---
|
||||
|
||||
Here is the list of methods provided by `driver` when you initialize it.
|
||||
|
||||
> **Note:** We have omitted the configuration options for brevity. Please look at the configuration section for the options. Links are provided in the description below.
|
||||
|
||||
```javascript
|
||||
import { driver } from "driver.js";
|
||||
import "driver.js/dist/driver.css";
|
||||
|
||||
// Look at the configuration section for the options
|
||||
// https://driverjs.com/docs/configuration#driver-configuration
|
||||
const driverObj = driver({ /* ... */ });
|
||||
|
||||
// --------------------------------------------------
|
||||
// driverObj is an object with the following methods
|
||||
// --------------------------------------------------
|
||||
|
||||
// Start the tour using `steps` given in the configuration
|
||||
driverObj.drive(); // Starts at step 0
|
||||
driverObj.drive(4); // Starts at step 4
|
||||
|
||||
driverObj.moveNext(); // Move to the next step
|
||||
driverObj.movePrevious(); // Move to the previous step
|
||||
driverObj.moveTo(4); // Move to the step 4
|
||||
driverObj.hasNextStep(); // Is there a next step
|
||||
driverObj.hasPreviousStep() // Is there a previous step
|
||||
|
||||
driverObj.getActiveIndex(); // Gets the active step index
|
||||
|
||||
driverObj.getActiveStep(); // Gets the active step configuration
|
||||
driverObj.getPreviousStep(); // Gets the previous step configuration
|
||||
driverObj.getActiveElement(); // Gets the active HTML element
|
||||
driverObj.getPreviousElement(); // Gets the previous HTML element
|
||||
|
||||
// Is the tour or highlight currently active
|
||||
driverObj.isActive();
|
||||
|
||||
// Recalculate and redraw the highlight
|
||||
driverObj.refresh();
|
||||
|
||||
// Look at the configuration section for configuration options
|
||||
// https://driverjs.com/docs/configuration#driver-configuration
|
||||
driverObj.getConfig();
|
||||
driverObj.setConfig({ /* ... */ });
|
||||
|
||||
// Look at the state section of configuration for format of the state
|
||||
// https://driverjs.com/docs/configuration#state
|
||||
driverObj.getState();
|
||||
|
||||
// Look at the DriveStep section of configuration for format of the step
|
||||
// https://driverjs.com/docs/configuration/#drive-step-configuration
|
||||
driverObj.highlight({ /* ... */ }); // Highlight an element
|
||||
```
|
||||
@@ -10,104 +10,7 @@ Driver.js is built to be highly configurable. You can configure the driver globa
|
||||
|
||||
> Driver.js is written in TypeScript. Configuration options are mostly self-explanatory. Also, if you're using an IDE like WebStorm or VSCode, you'll get autocomplete and documentation for all the configuration options.
|
||||
|
||||
## Popover Configuration
|
||||
|
||||
The popover is the main UI element of Driver.js. It's the element that highlights the target element, and shows the step content. You can configure the popover globally, or per step. Given below are some of the available configuration options.
|
||||
|
||||
```typescript
|
||||
type Popover = {
|
||||
// Title and descriptions shown in the popover.
|
||||
// You can use HTML in these. Also, you can
|
||||
// omit one of these to show only the other.
|
||||
title?: string;
|
||||
description?: string;
|
||||
|
||||
// The position and alignment of the popover
|
||||
// relative to the target element.
|
||||
side?: "top" | "right" | "bottom" | "left";
|
||||
align?: "start" | "center" | "end";
|
||||
|
||||
// Array of buttons to show in the popover.
|
||||
// When highlighting a single element, there
|
||||
// are no buttons by default. When showing
|
||||
// a tour, the default buttons are "next",
|
||||
// "previous" and "close".
|
||||
showButtons?: ("next" | "previous" | "close")[];
|
||||
// An array of buttons to disable. This is
|
||||
// useful when you want to show some of the
|
||||
// buttons, but disable some of them.
|
||||
disableButtons?: ("next" | "previous" | "close")[];
|
||||
|
||||
// Text to show in the buttons. `doneBtnText`
|
||||
// is used on the last step of a tour.
|
||||
nextBtnText?: string;
|
||||
prevBtnText?: string;
|
||||
doneBtnText?: string;
|
||||
|
||||
// Whether to show the progress text in popover.
|
||||
showProgress?: boolean;
|
||||
// Template for the progress text. You can use
|
||||
// the following placeholders in the template:
|
||||
// - {{current}}: The current step number
|
||||
// - {{total}}: Total number of steps
|
||||
// Defaults to following if `showProgress` is true:
|
||||
// - "{{current}} of {{total}}"
|
||||
progressText?: string;
|
||||
|
||||
// Custom class to add to the popover element.
|
||||
// This can be used to style the popover.
|
||||
popoverClass?: string;
|
||||
|
||||
// Hook to run after the popover is rendered.
|
||||
// You can modify the popover element here.
|
||||
// Parameter is an object with references to
|
||||
// the popover DOM elements such as buttons
|
||||
// title, descriptions, body, etc.
|
||||
onPopoverRendered?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;
|
||||
|
||||
// Callbacks for button clicks. You can use
|
||||
// these to add custom behavior to the buttons.
|
||||
// Each callback receives the following parameters:
|
||||
// - element: The current DOM element of the step
|
||||
// - step: The step object configured for the step
|
||||
// - options.config: The current configuration options
|
||||
// - options.state: The current state of the driver
|
||||
onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
}
|
||||
```
|
||||
|
||||
## Drive Step Configuration
|
||||
|
||||
Drive step is the configuration object passed to the `highlight` method or the `steps` array of the `drive` method. You can configure the popover and the target element for each step. Given below are some of the available configuration options.
|
||||
|
||||
```typescript
|
||||
type DriveStep = {
|
||||
// The target element to highlight.
|
||||
// This can be a DOM element, or a CSS selector.
|
||||
// If this is a selector, the first matching
|
||||
// element will be highlighted.
|
||||
element: Element | string;
|
||||
|
||||
// The popover configuration for this step.
|
||||
// Look at the Popover Configuration section
|
||||
popover?: Popover;
|
||||
|
||||
// Callback when the current step is deselected,
|
||||
// about to be highlighted or highlighted.
|
||||
// Each callback receives the following parameters:
|
||||
// - element: The current DOM element of the step
|
||||
// - step: The step object configured for the step
|
||||
// - options.config: The current configuration options
|
||||
// - options.state: The current state of the driver
|
||||
onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
}
|
||||
```
|
||||
|
||||
## Global Configuration
|
||||
## Driver Configuration
|
||||
|
||||
You can configure the driver globally by passing the configuration object to the `driver` call or by using the `setConfig` method. Given below are some of the available configuration options.
|
||||
|
||||
@@ -207,6 +110,103 @@ type Config = {
|
||||
>
|
||||
> `onNextClick` and `onPrevClick` hooks can be configured at the step level as well. When configured at the driver level, you control the navigation for all the steps. When configured at the step level, you control the navigation for that particular step only.
|
||||
|
||||
## Popover Configuration
|
||||
|
||||
The popover is the main UI element of Driver.js. It's the element that highlights the target element, and shows the step content. You can configure the popover globally, or per step. Given below are some of the available configuration options.
|
||||
|
||||
```typescript
|
||||
type Popover = {
|
||||
// Title and descriptions shown in the popover.
|
||||
// You can use HTML in these. Also, you can
|
||||
// omit one of these to show only the other.
|
||||
title?: string;
|
||||
description?: string;
|
||||
|
||||
// The position and alignment of the popover
|
||||
// relative to the target element.
|
||||
side?: "top" | "right" | "bottom" | "left";
|
||||
align?: "start" | "center" | "end";
|
||||
|
||||
// Array of buttons to show in the popover.
|
||||
// When highlighting a single element, there
|
||||
// are no buttons by default. When showing
|
||||
// a tour, the default buttons are "next",
|
||||
// "previous" and "close".
|
||||
showButtons?: ("next" | "previous" | "close")[];
|
||||
// An array of buttons to disable. This is
|
||||
// useful when you want to show some of the
|
||||
// buttons, but disable some of them.
|
||||
disableButtons?: ("next" | "previous" | "close")[];
|
||||
|
||||
// Text to show in the buttons. `doneBtnText`
|
||||
// is used on the last step of a tour.
|
||||
nextBtnText?: string;
|
||||
prevBtnText?: string;
|
||||
doneBtnText?: string;
|
||||
|
||||
// Whether to show the progress text in popover.
|
||||
showProgress?: boolean;
|
||||
// Template for the progress text. You can use
|
||||
// the following placeholders in the template:
|
||||
// - {{current}}: The current step number
|
||||
// - {{total}}: Total number of steps
|
||||
// Defaults to following if `showProgress` is true:
|
||||
// - "{{current}} of {{total}}"
|
||||
progressText?: string;
|
||||
|
||||
// Custom class to add to the popover element.
|
||||
// This can be used to style the popover.
|
||||
popoverClass?: string;
|
||||
|
||||
// Hook to run after the popover is rendered.
|
||||
// You can modify the popover element here.
|
||||
// Parameter is an object with references to
|
||||
// the popover DOM elements such as buttons
|
||||
// title, descriptions, body, etc.
|
||||
onPopoverRendered?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;
|
||||
|
||||
// Callbacks for button clicks. You can use
|
||||
// these to add custom behavior to the buttons.
|
||||
// Each callback receives the following parameters:
|
||||
// - element: The current DOM element of the step
|
||||
// - step: The step object configured for the step
|
||||
// - options.config: The current configuration options
|
||||
// - options.state: The current state of the driver
|
||||
onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
|
||||
}
|
||||
```
|
||||
|
||||
## Drive Step Configuration
|
||||
|
||||
Drive step is the configuration object passed to the `highlight` method or the `steps` array of the `drive` method. You can configure the popover and the target element for each step. Given below are some of the available configuration options.
|
||||
|
||||
```typescript
|
||||
type DriveStep = {
|
||||
// The target element to highlight.
|
||||
// This can be a DOM element, or a CSS selector.
|
||||
// If this is a selector, the first matching
|
||||
// element will be highlighted.
|
||||
element: Element | string;
|
||||
|
||||
// The popover configuration for this step.
|
||||
// Look at the Popover Configuration section
|
||||
popover?: Popover;
|
||||
|
||||
// Callback when the current step is deselected,
|
||||
// about to be highlighted or highlighted.
|
||||
// Each callback receives the following parameters:
|
||||
// - element: The current DOM element of the step
|
||||
// - step: The step object configured for the step
|
||||
// - options.config: The current configuration options
|
||||
// - options.state: The current state of the driver
|
||||
onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
|
||||
}
|
||||
```
|
||||
|
||||
## State
|
||||
|
||||
You can access the current state of the driver by calling the `getState` method. It's also passed to the hooks and callbacks.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: "Theming"
|
||||
groupTitle: "Introduction"
|
||||
sort: 3
|
||||
sort: 5
|
||||
---
|
||||
|
||||
You can customize the look and feel of the driver by adding custom class to popover or applying CSS to different classes used by driver.js.
|
||||
@@ -53,7 +53,7 @@ Here is the list of classes applied to the popover which you can use in conjunct
|
||||
.driver-popover-next-btn {}
|
||||
```
|
||||
|
||||
Visit the [example page](/docs/styling-popover) for a demo that modifies the popover styles.
|
||||
Visit the [example page](/docs/styling-popover) for an example that modifies the popover styles.
|
||||
|
||||
## Modifying Popover DOM
|
||||
|
||||
|
||||
@@ -56,6 +56,16 @@ export function driver(options: Config = {}) {
|
||||
}
|
||||
}
|
||||
|
||||
function moveTo(index: number) {
|
||||
const steps = getConfig("steps") || [];
|
||||
|
||||
if (steps[index]) {
|
||||
drive(index);
|
||||
} else {
|
||||
destroy();
|
||||
}
|
||||
}
|
||||
|
||||
function handleArrowLeft() {
|
||||
const isTransitioning = getState("__transitionCallback");
|
||||
if (isTransitioning) {
|
||||
@@ -253,8 +263,14 @@ export function driver(options: Config = {}) {
|
||||
setConfig: configure,
|
||||
getConfig,
|
||||
getState,
|
||||
getActiveIndex: () => getState("activeIndex"),
|
||||
getActiveStep: () => getState("activeStep"),
|
||||
getActiveElement: () => getState("activeElement"),
|
||||
getPreviousElement: () => getState("previousElement"),
|
||||
getPreviousStep: () => getState("previousStep"),
|
||||
moveNext,
|
||||
movePrevious,
|
||||
moveTo,
|
||||
hasNextStep: () => {
|
||||
const steps = getConfig("steps") || [];
|
||||
const activeIndex = getState("activeIndex");
|
||||
|
||||
Reference in New Issue
Block a user