1 | <p align="center">
|
2 | <img src="https://raw.githubusercontent.com/PoslinskiNet/ember-introjs/master/ember-introjs.png" alt="Ember Custom Actions Logo" width="100%">
|
3 | </p>
|
4 |
|
5 | [![Build Status](https://api.travis-ci.org/PoslinskiNet/ember-introjs.svg?branch=master)](http://travis-ci.org/PoslinskiNet/ember-introjs)
|
6 | [![Greenkeeper badge](https://badges.greenkeeper.io/PoslinskiNet/ember-introjs.svg)](https://greenkeeper.io/)
|
7 | [![Ember Observer Score](https://emberobserver.com/badges/ember-pell.svg)](https://emberobserver.com/addons/ember-pell)
|
8 |
|
9 | Ember IntroJS wraps [introjs][intro-js] in an Ember Component to guide
|
10 | users through your app.
|
11 |
|
12 | ## Installation
|
13 |
|
14 | `ember install ember-introjs`
|
15 |
|
16 | ## Usage
|
17 |
|
18 | ### 1st option (recommended)
|
19 | #### Use `intro-js/step` component as a wrapper
|
20 |
|
21 | ```hbs
|
22 | {{#intro-js/step step=1 intro="Step Component"}}
|
23 | <h1>Hello!</h1>
|
24 | {{/intro-js/step}}
|
25 | ```
|
26 |
|
27 | You can customize wrapper using:
|
28 | - `position="top"`
|
29 | - `intro="Welcome!"`
|
30 | - `tooltipClass="tooltip-class"`
|
31 | - `highlightClass="highlight-class"`
|
32 | - `position="top"`
|
33 | - `hint="Use it :)"`
|
34 | - `hintPosition="bottom-left"`
|
35 |
|
36 | Options are documented in the code as well as in [IntroJS Docs](http://introjs.com/docs)
|
37 |
|
38 | ### 2nd option
|
39 | #### 1. Declare your steps:
|
40 | You can declare an array in JavaScript in your controller or parent component:
|
41 |
|
42 | ```javascript
|
43 | // app/controllers/ticket.js
|
44 | import Controller from '@ember/controller';
|
45 | import { computed } from '@ember/object';
|
46 |
|
47 | export default Controller.extend({
|
48 | steps: computed(function() {
|
49 | return [
|
50 | {
|
51 | element: $('#step1'),
|
52 | intro: 'Step 1!'
|
53 | },
|
54 | {
|
55 | element: $('#step2'),
|
56 | intro: 'Step2!'
|
57 | }
|
58 | ];
|
59 | })
|
60 | });
|
61 | ```
|
62 |
|
63 | ### 2. Use `intro-js` component
|
64 | Then to use the steps, you can use the steps in your handlebars template:
|
65 |
|
66 | ```handlebars
|
67 | {{! app/templates/ticket }}
|
68 | {{intro-js start-if=true}}
|
69 | ```
|
70 |
|
71 | ## Action Hooks
|
72 |
|
73 | 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:
|
74 |
|
75 | ```javascript
|
76 | // app/routes/ticket.js
|
77 | import Ember from 'ember';
|
78 |
|
79 | export default Ember.Route.extend({
|
80 | actions: {
|
81 | introBeforeChange(previousStep, nextStep, introJSComponent,
|
82 | elementOfNewStep){
|
83 | // You could track user interactions here, e.g. analytics.
|
84 | this.sendAnalytics(prevStep);
|
85 | }
|
86 | }
|
87 | });
|
88 | ```
|
89 |
|
90 | Then pass the name of the action in the handlebars helper that renders
|
91 | the component below.
|
92 |
|
93 | ```handlebars
|
94 | {{intro-js steps=steps start-if=true on-before-change="introBeforeChange"}}
|
95 | ```
|
96 |
|
97 | ### on-before-change (currentStep, nextStep, introJSComponent, nextElement)
|
98 |
|
99 | Called when the user clicks next (or uses their keyboard). Called before
|
100 | `on-change`. Given the currentStep, the nextStep, the introJSComponent,
|
101 | and the DOM element of the next step.
|
102 |
|
103 | ### on-change (step, introJSComponent, currentElement)
|
104 |
|
105 | Called after `on-before-change` when the user moves a step (backwards or
|
106 | forward) in the introduction. Gives the current step, the introJS
|
107 | component isntance, and the element of the current step.
|
108 |
|
109 | ### on-after-change (step, introJSComponent, currentElement)
|
110 |
|
111 | Called after `on-change` when the user moves a step (backwards or
|
112 | forward) in the introduction. Gives the current step, the introJS
|
113 | component isntance, and the element of the current step.
|
114 |
|
115 | ### on-exit (step, introJSComponent)
|
116 |
|
117 | Called when the user quits the intro via the "Skip" button, hitting
|
118 | `escape`, or clicking outside the overlay. Given the current step, and
|
119 | the introJS component.
|
120 |
|
121 | ### on-complete (step, introJSComponent)
|
122 |
|
123 | Called when the user finishes the intro by clicking "Done" or hitting
|
124 | right on the keyboard until the end. Called with the last step and the
|
125 | introJS component instance.
|
126 |
|
127 | ## Intro JS Options
|
128 |
|
129 | Intro JS has a variety of options available to it. You can see the full
|
130 | list [here](https://github.com/usablica/intro.js#options), but we also
|
131 | provided the full list below. You'll notice that in the list below
|
132 | options all follow the dasherized convention of HTML and ember-cli
|
133 | filenames. The original list uses camelCase names, and so does IntroJS.
|
134 | Ember IntroJS will do the conversion for you.
|
135 |
|
136 | You can also set other options using the Handlebars helper syntax:
|
137 | `
|
138 | ```handlebars
|
139 | {{intro-js steps=steps show-bullets=true}}
|
140 | ```
|
141 |
|
142 | Or you could extend your own base class to override defaults
|
143 | instead of specifying them every time in the Handlebars helper:
|
144 |
|
145 | ```javascript
|
146 | myapp/app/components/my-intro-js.js
|
147 | import IntroJSComponent from 'ember-introjs/components/intro-js';
|
148 |
|
149 | export default IntroJSComponent.extend({
|
150 | 'exit-on-esc': true
|
151 | });
|
152 | ```
|
153 |
|
154 | You can also reopen the class:
|
155 |
|
156 | ```javascript
|
157 | import IntroJSComponent from 'ember-introjs/components/intro-js';
|
158 |
|
159 | IntroJSComponent.reopen({
|
160 | 'exit-on-esc': true
|
161 | });
|
162 | ```
|
163 |
|
164 | - `steps`: For defining steps using JSON configuration (see
|
165 | [this](https://github.com/usablica/intro.js/blob/master/example/programmatic/index.html)
|
166 | example)
|
167 | - `next-label`: Next button label
|
168 | - `prev-label`: Previous button label
|
169 | - `skip-label`: Skip button label
|
170 | - `done-label`: Done button label
|
171 | - `tooltip-position`: Default tooltip position
|
172 | - `tooltip-class`: Adding CSS class to all tooltips
|
173 | - `highlight-class`: Additional CSS class for the helperLayer
|
174 | - `exit-on-esc`: Exit introduction when pressing Escape button, `true` or
|
175 | `false`
|
176 | - `exit-on-overlay-click`: Exit introduction when clicking on overlay
|
177 | layer, `true` or `false`
|
178 | - `show-step-numbers`: Show steps number in the red circle or not, `true`
|
179 | or `false`
|
180 | - `keyboard-navigation`: Navigating with keyboard or not, `true` or
|
181 | `false`
|
182 | - `show-buttons`: Show introduction navigation buttons or not, `true` or
|
183 | `false`
|
184 | - `show-bullets`: Show introduction bullets or not, `true` or `false`
|
185 | - `show-progress`: Show introduction progress or not, `true` or `false`
|
186 | - `scroll-to-element`: Auto scroll to highlighted element if it's outside
|
187 | of viewport, `true` or `false`
|
188 | - `overlay-opacity`: Adjust the overlay opacity, `Number`
|
189 | - `disable-interaction`: Disable an interaction inside element or not,
|
190 | `true` or `false`
|
191 |
|
192 | See
|
193 | [setOption](https://github.com/usablica/intro.js/#introjssetoptionoption-value)
|
194 | to see an example.
|
195 |
|
196 | ### Testing Helpers
|
197 |
|
198 | Ember IntroJS comes with a set of testing helpers.
|
199 |
|
200 | To use them, first import them in your `tests/test-helper.js` file:
|
201 |
|
202 | ```javascript
|
203 | // tests/test-helpers.js
|
204 | import './helpers/ember-introjs';
|
205 | ```
|
206 |
|
207 | ## Running Tests
|
208 |
|
209 | * `ember test`
|
210 | * `ember test --server`
|
211 |
|
212 | ## Building
|
213 |
|
214 | * `ember build`
|
215 |
|
216 | For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
|
217 |
|
218 | ## LICENSE
|
219 |
|
220 | See the LICENSE file included in this repository.
|
221 |
|
222 | 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 link bellow:
|
223 |
|
224 |
|
225 | [intro-js]: https://github.com/usablica/intro.js/
|
226 | [hooks]: https://github.com/usablica/intro.js#introjsstart
|
227 |
|
228 |
|
229 | ## Code of Conduct
|
230 | Please note that this project is released with a Contributor Code of
|
231 | Conduct. By participating in this project you agree to abide by its
|
232 | terms, which can be found in the `CODE_OF_CONDUCT.md` file in this
|
233 | repository.
|