Skip to content
This repository has been archived by the owner on Jan 12, 2021. It is now read-only.

Latest commit

 

History

History
264 lines (214 loc) · 7.44 KB

README.md

File metadata and controls

264 lines (214 loc) · 7.44 KB
Raw

vue-introjs

intro.js bindings for Vue.

Installation

Add package

yarn add vue-introjs

# or via npm:
npm i vue-introjs

Install plugin

import VueIntro from 'vue-introjs';
Vue.use(VueIntro);

Use CDN version of introJs

Make sure you have installed and attached intro.js scripts and styles to the page. This plugin does not come with intro.js built-in.

The motivation of it is to give the developer more control on intro.js versions.

Use with webpack and vue-cli

Install required dependency:

yarn add intro.js

# or via npm:
npm i intro.js

As this plugin relies on global introJs variable, webpack should provide it:

// webpack.config.js
{
    plugins: [
        new webpack.ProvidePlugin({
            // other modules
            introJs: ['intro.js']
        })
    ]
}

// attach CSS
// SomeComponent.vue
import 'intro.js/introjs.css';

If you are using vue-cli this can be done with the following lines in your vue.config.js:

// vue.config.js
const webpack = require('webpack');

module.exports = {
  configureWebpack: {
    plugins: [
      new webpack.ProvidePlugin({
        'introJs': ['intro.js']
      })
    ]
  },
}

Use with vue-cli and webpack template

Add to your src/main.js something like this for global, or per SFC like above:

import VueIntro from 'vue-introjs'
Vue.use(VueIntro)

import 'intro.js/introjs.css';

then add into the plugins sections of build/webpack.dev.conf.js and build/webpack.prod.conf.js the new webpack.ProvidePlugin({ section from above.

Don't forget to install intro.js though and save it (via yarn or npm). The webpack.ProvidePlugin will pull it in, so no need to import introJs from 'intro.js' in src/main.js

Use with NuxtJs

Make sure you install vue-introjs and intro.js then create a Nuxt plugin in /plugins

//plugins/vue-introjs.js`
import Vue from 'vue'
import VueIntro from 'vue-introjs'
import 'intro.js/introjs.css'

Vue.use(VueIntro)

then add it to your nuxt.config.js list of plugins

//nuxt.config.js`
plugins: [
    // ..
    { src: '~plugins/vue-introjs.js', mode: 'client' },
]

Finally register introjs by adding it as a webpack plugin and you're set

//nuxt.config.js
import webpack from 'webpack'

export default {
    build: {
        // ..
        plugins: [
            new webpack.ProvidePlugin({
                introJs: ['intro.js'],
            }),
        ],
    }
}

Contents

The plugin extends Vue with a set of directives and $intro() constructor function.

Define steps and hints

Directives, to define introductional steps:

Steps

The tooltip text of step.
<div v-intro="'The content of tooltip'"></div>
Optionally define the number (priority) of step.
<div v-intro="'The content of tooltip'" v-intro-step="2"></div>
Optionally define a CSS class for tooltip.
<div v-intro="'The content of tooltip'" v-intro-tooltip-class="'red-bg'"></div>
Optionally append a CSS class to the helperLayer.
<div v-intro="'The content of tooltip'" v-intro-highlight-class="'blue-bg'"></div>
Optionally define the position of tooltip, `top`, `left`, `right`, `bottom`, `bottom-left-aligned` (same as `bottom`), `bottom-middle-aligned`, `bottom-right-aligned` or `auto` (to detect the position of element and assign the correct position automatically). Default is `bottom`.
<div v-intro="'The content of tooltip'" v-intro-position="'top'"></div>
Optionally define the element to scroll to, `element` or `tooltip`. Default is `element`.
<div v-intro="'The content of tooltip'" v-intro-scroll-to="'element'"></div>
To disable interactions with elements inside the highlighted box, `true` or `false` (also `1` or `0`).
<div v-intro="'The content of tooltip'" v-intro-disable-interaction="false"></div>

More about intro steps

Hints

Directives, to define hints:

The tooltip text of hint.
<div v-intro-hint="'The content of tooltip'"></div>
Optionally define the position of hint. Options: `top-middle`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `bottom-middle`, `middle-left`, `middle-right`, `middle-middle`. Default: `top-middle`.
<div v-intro-hint="'The content of tooltip'" v-intro-position="'top'"></div>

More about hints

Also refer example directory for live examples.

Usage

Once all steps are defined, call start() or showHints() to start the show:

// SomeComponent.vue
{
    mounted() {
        this.$intro().start(); // start the guide
        this.$intro().showHints(); // show hints
    }
}

Configuration

When the defaults are not enough, then fine tuning is required. Construct a new introJs instance and configure in own way:

this.$intro('#intro-farm'); // //start introduction for element id='intro-farm'
this.$intro().addStep({}); // Add a new step to introJs programmatically.

Basically, $intro() returns a new introJs instance which then can be configured usign it's API.

Registering callbacks

Just call this.$intro().<callback-name>. Example:

// SomeComponent
this.$intro().oncomplete(function () {
    console.log('completed');
});

Autostart

If tour should start automatically when all directives loaded, add v-intro-autostart="true" directive. Also extra configuration required for plugin:

import VueIntro from 'intro.js';
Vue.use(VueIntro, {
    waitTimeout: 400
});

For hints use v-intro-autostart:hints="true".

How it works

The plugin starts a timer with waitTimeout. Every v-intro directive restarts that timer. This lets the plugin to wait for async components, router views or other components to load before tour will be autostarted.

Configure intro.js instance

Add v-intro-autostart.config next to v-intro-autostart with intro.js configuration object as an argument. That object then passed to introJs(obj) constructor.

<div v-intro-autostart="true" v-intro-autostart.config="{ doneLabel: 'DONE!' }"></div>

Listening for intro.js events

It is possible to add event listeners to automatically started tour. The format is:

v-intro-autostart:on.<event-name>="<callback>"

where event-name is any of intro.js supported hooks (see intro.js hooks) for more details. Same applies to hints.

Note, the plugin defines two more events, designed to work with the autostart feature: onautostart and onautostarthints. These callbacks receive two arguments: element and current introjs instance.

For example:

<div v-intro-autostart="true" v-intro-autostart:on.complete="onComplete"></div>
<div v-intro-autostart="true" v-intro-autostart:on.autostart="onAutostarted"></div>

Conditional steps and hints

When it is required to bind intro only when some expression evaluates to true, use v-intro-if directive. It accepts any valid expression that evaluates to either true or false:

<div v-intro="'Conditional step'" v-intro-if="item.id == 1" v-for="item in items" :key="item.id"></div>

Note, that v-intro-if directive must go after v-intro.

Credits

  1. http://introjs.com
  2. Gabriel J Perez Irizarry