Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/poslinskinet/ember-introjs

An Ember Component for intro.js
https://github.com/poslinskinet/ember-introjs

ember-addon emberjs introjs introjs-component javascript

Last synced: 4 days ago
JSON representation

An Ember Component for intro.js

Host: GitHub
URL: https://github.com/poslinskinet/ember-introjs
Owner: PoslinskiNet
License: mit
Created: 2015-01-28T23:16:03.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2023-07-11T04:51:27.000Z (over 1 year ago)
Last Synced: 2024-12-11T00:03:53.549Z (11 days ago)
Topics: ember-addon, emberjs, introjs, introjs-component, javascript
Language: JavaScript
Size: 5.17 MB
Stars: 82
Watchers: 4
Forks: 29
Open Issues: 13
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        


  



[![Build Status](https://api.travis-ci.org/PoslinskiNet/ember-introjs.svg?branch=master)](http://travis-ci.org/PoslinskiNet/ember-introjs)

[![Greenkeeper badge](https://badges.greenkeeper.io/PoslinskiNet/ember-introjs.svg)](https://greenkeeper.io/)

[![Ember Observer Score](https://emberobserver.com/badges/ember-pell.svg)](https://emberobserver.com/addons/ember-pell)

[![NPM package info for ember-introjs](https://img.shields.io/npm/dm/ember-introjs.svg)](http://npmjs.com/package/ember-introjs)   [![License info](https://img.shields.io/npm/l/ember-introjs.svg)](http://npmjs.com/package/ember-introjs)

Ember IntroJS wraps [introjs][intro-js] in an Ember Component to guide

users through your app.

Compatibility

------------------------------------------------------------------------------

* Ember.js v2.18 or above

* Ember CLI v2.13 or above

* Node.js v8 or above

Installation

------------------------------------------------------------------------------

`ember install ember-introjs`

## Usage

### 1st option (recommended)

#### Use `intro-js/step` component as a wrapper

```handlebars

{{#intro-js/step step=1 intro="Step Component"}}

  
Hello!

{{/intro-js/step}}

```

You can customize wrapper using:

- `position="top"`

- `intro="Welcome!"`

- `tooltipClass="tooltip-class"`

- `highlightClass="highlight-class"`

- `position="top"`

- `hint="Use it :)"`

- `hintPosition="bottom-left"`

Options are documented in the code as well as in [IntroJS Docs](http://introjs.com/docs)

### 2nd option

#### 1. Declare your steps:

You can declare an array in JavaScript in your controller or parent component:

```javascript

// app/controllers/ticket.js

import Controller from '@ember/controller';

import { computed } from '@ember/object';

export default Controller.extend({

  steps: computed(function() {

    return [

      {

        element: $('#step1'),

        intro: 'Step 1!'

      },

      {

        element: $('#step2'),

        intro: 'Step2!'

      }

    ];

  })

});

```

### 2. Use `intro-js` component

Then to use the steps, you can use the steps in your handlebars template:

```handlebars

{{! app/templates/ticket }}

{{intro-js start-if=true}}

```

## Action Hooks

IntroJS supports a series of hooks for getting notified for when users switch between steps or exit. You can subscribe to these actions using the typical `actions` hash in your Route or Controller:

```javascript

// app/routes/ticket.js

import Ember from 'ember';

export default Ember.Route.extend({

  actions: {

    introBeforeChange(previousStep, nextStep, introJSComponent,

elementOfNewStep){

      // You could track user interactions here, e.g. analytics.

      this.sendAnalytics(prevStep);

    }

  }

});

```

Then pass the name of the action in the handlebars helper that renders

the component below.

```handlebars

{{intro-js steps=steps start-if=true on-before-change=(action "introBeforeChange")}}

```

### on-before-change (currentStep, nextStep, introJSComponent, nextElement)

Called when the user clicks next (or uses their keyboard). Called before

`on-change`. Given the currentStep, the nextStep, the introJSComponent,

and the DOM element of the next step.

### on-change (step, introJSComponent, currentElement)

Called after `on-before-change` when the user moves a step (backwards or

forward) in the introduction. Gives the current step, the introJS

component isntance, and the element of the current step.

### on-after-change (step, introJSComponent, currentElement)

Called after `on-change` when the user moves a step (backwards or

forward) in the introduction. Gives the current step, the introJS

component isntance, and the element of the current step.

### on-before-exit (step, introJSComponent)

Called when the user quits the intro via the "Skip" button, hitting

`escape`, or clicking outside the overlay. Given the current step, and

the introJS component.

### on-exit (step, introJSComponent)

Called after `on-before-exit` when the user quits the intro via the "Skip" button, hitting

`escape`, or clicking outside the overlay. Given the current step, and

the introJS component.

### on-complete (step, introJSComponent)

Called when the user finishes the intro by clicking "Done" or hitting

right on the keyboard until the end. Called with the last step and the

introJS component instance.

## Intro JS Options

Intro JS has a variety of options available to it. You can see the full

list [here](https://github.com/usablica/intro.js#options), but we also

provided the full list below. You'll notice that in the list below

options all follow the dasherized convention of HTML and ember-cli

filenames. The original list uses camelCase names, and so does IntroJS.

Ember IntroJS will do the conversion for you.

You can also set other options using the Handlebars helper syntax:

`

```handlebars

{{intro-js steps=steps show-bullets=true}}

```

Or you could extend your own base class to override defaults

instead of specifying them every time in the Handlebars helper:

```javascript

myapp/app/components/my-intro-js.js

import IntroJSComponent from 'ember-introjs/components/intro-js';

export default IntroJSComponent.extend({

  'exit-on-esc': true

});

```

You can also reopen the class:

```javascript

import IntroJSComponent from 'ember-introjs/components/intro-js';

IntroJSComponent.reopen({

  'exit-on-esc': true

});

```

| property | description |

|---|---|

| `steps` | For defining steps using JSON configuration (see [this](https://github.com/usablica/intro.js/blob/master/example/programmatic/index.html) example) |

| `next-label` | Next button label |

| `prev-label` | Previous button label |

| `skip-label` | Skip button label |

| `done-label` | Done button label |

| `tooltip-position` | Default tooltip position |

| `tooltip-class` | Adding CSS class to all tooltips |

| `highlight-class` | Additional CSS class for the helperLayer |

| `exit-on-esc` | Exit introduction when pressing Escape button, `true` or `false` |

| `exit-on-overlay-click` | Exit introduction when clicking on overlay layer, `true` or `false` |

| `show-step-numbers` | Show steps number in the red circle or not, `true` or `false` |

| `keyboard-navigation` | Navigating with keyboard or not, `true` or `false` |

| `show-buttons` | Show introduction navigation buttons or not, `true` or `false` |

| `show-bullets` | Show introduction bullets or not, `true` or `false` |

| `show-progress` | Show introduction progress or not, `true` or `false` |

| `scroll-to-element` | Auto scroll to highlighted element if it's outside of viewport, `true` or `false` |

| `overlay-opacity` | Adjust the overlay opacity, `Number` |

| `disable-interaction` | Disable an interaction inside element or not, `true` or `false` |

| `helper-element-padding` | Set how much padding to be used around helper element |

See [setOption](https://github.com/usablica/intro.js/#introjssetoptionoption-value) to see an example.

### Testing Helpers

Ember IntroJS comes with a set of testing helpers.

To use them, first import them in your `tests/test-helper.js` file:

```javascript

// tests/test-helpers.js

import './helpers/ember-introjs';

```

License

------------------------------------------------------------------------------

See the LICENSE file included in this repository.

Keep in mind that if you like to use Intro.JS for commercial use, you should buy a commercial license. You can find more information on the intro.js project site: https://introjs.com/#commercial

[intro-js]: https://github.com/usablica/intro.js/

[hooks]: https://github.com/usablica/intro.js#introjsstart

Contributing

------------------------------------------------------------------------------

See the [Contributing](CONTRIBUTING.md) guide for details.

## Code of Conduct

Please note that this project is released with a Contributor Code of

Conduct. By participating in this project you agree to abide by its

terms, which can be found in the `CODE_OF_CONDUCT.md` file in this

repository.