Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gerrproger/tutorjs
Smart tutorials for site users
https://github.com/gerrproger/tutorjs
Last synced: about 2 months ago
JSON representation
Smart tutorials for site users
- Host: GitHub
- URL: https://github.com/gerrproger/tutorjs
- Owner: Gerrproger
- License: gpl-2.0
- Created: 2014-08-18T08:46:49.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-04-07T14:42:23.000Z (9 months ago)
- Last Synced: 2024-04-24T17:41:03.026Z (8 months ago)
- Language: JavaScript
- Homepage: http://gerrproger.github.io/TutorJS/
- Size: 93.8 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TutorJS
**Interactive step-by-step tutorials with elements highlighting for your website, made with SVG.**
### Browser compatibility
- IE 9+
- All other popular browsers
### Dependences
- None
### License
- [https://github.com/Gerrproger/TutorJS/blob/master/LICENSE](https://github.com/Gerrproger/TutorJS/blob/master/LICENSE)
### You can use Bower or NPM for installation:
`npm install tutorjs`\
`yarn add tutorjs`\
`bower install tutorjs`
# Usage
Include the script in the `` of your document:
```html
```
Place code in the `` of your document:
```html
...
```
_Note:_ You can change svg styles as you like!
And just start your tutorial:
```javascript
tutorJS.start(
[
{
element: 'someId',
caption: 'This is it!',
},
{
element: 'anotherId',
position: 'top',
},
],
{
auto: 4000,
time: 400,
}
);
```
# Api
## start
The main method that starts your tutorial.
```javascript
tutorJS.start(elements, options);
```
_Note:_ You can start the new tutorial not even quitting the previous!
#### elements
An array of objects or just an object with steps data for your tutorial.
```javascript
[
{
element: 'someId',
captions: 'My element',
},
{
element: 'anotherId',
position: 'top',
onActive: function () {},
},
];
```
**Type:** array of objects / object
**Required:** yes
#### options
An object with options for this tutorial instance.
```javascript
{
auto: 1000,
onQuit: function(){},
showHint: false
}
```
**Type:** object
**Required:** no
### element.element
An element to highlight. Can be the `id` or DOM object or coordinates object (`{top: <>, left: <>, width: <>, height: <>}` in px).
```javascript
element: 'someId'
// or
element: {top: 100, left: 100, width: 50, height: 50}
```
**Type:** string / DOM obj / coordianates
**Required:** yes
### element.caption
Text that will be displayed on the hint when the element is highlighted
```javascript
caption: 'This is some super button!';
```
**Type:** string
**Default:** null
**Required:** no
### element.position
Position of the hint related to the element. Can be `left`, `top`, `right` or `bottom`.
```javascript
position: 'right';
```
**Type:** string
**Default:** bottom
**Required:** no
### element.onActive
Function that would be called when this element would be highlighted.
```javascript
onActive: function(element, step){ console.log('This is it!', element) }
```
**Type:** function
**Default:** null
**Required:** no
### options.auto
Automatically switches steps (autoplay). Just pass delay for viewing one step (ms). Pass `0` for no autoplaying.
```javascript
auto: 1000;
```
**Type:** number
**Default:** 0
**Required:** no
### options.onQuit
Function that is called on quitting active tutorial.
```javascript
onQuit: function(instance){ console.log('Tutor has ended!'); }
```
**Type:** function
**Default:** null
**Required:** no
### options.bgQuit
Quit this tutorial on the background dark layout click or not.
```javascript
bgQuit: false;
```
**Type:** boolen
**Default:** true
**Required:** no
### options.showNext
Show the `Next` button or not.
```javascript
showNext: false;
```
**Type:** boolen
**Default:** true
**Required:** no
### options.showQuit
Show the `Quit` button or not.
```javascript
showQuit: false;
```
**Type:** boolen
**Default:** true
**Required:** no
### options.showCount
Show the pagination or not.
```javascript
showCount: false;
```
**Type:** boolen
**Default:** true
**Required:** no
### options.showHint
Show the hint block or not.
```javascript
showHint: false;
```
**Type:** boolen
**Default:** true
**Required:** no
### options.time
The average duration of animations and effects in ms (this actually is the factor).
```javascript
time: 1000;
```
**Type:** number
**Default:** 300
**Required:** no
## quit
The method that quits your tutorial. No parametrs.
```javascript
tutorJS.quit();
```
## next
The method that shows the next step of your tutorial or quits it if no next step is available. No parametrs.
```javascript
tutorJS.next();
```
## recalc
Recalculates TutorJS elements positions (highlighting and the hint). No parameters.
```javascript
tutorJS.recalc();
```
## set
Reconfigures current tutorial options and the current element.
```javascript
tutorJS.set(options, element);
```
#### options
An object with options for the current tutorial instance (as in the start method).
**Required:** no
#### element
An object with the current step data for the current tutorial (as in the start method).
**Required:** no
---
## Getting data
You can get some data of the current tutorial and the current element.
#### Elements (steps)
```javascript
var elements = tutorJS.elements;
var stepsN = elements.length;
```
#### Current element
```javascript
var currentStep = tutorJS.activeEl;
```
#### Current step number
```javascript
var stepN = tutorJS.active;
```
#### Instance options
```javascript
var options = tutorJS.options;
```
#### TutorJS version
```javascript
var ver = tutorJS.VERSION;
```
# Utils
You can use some other methods of the TutorJS for your needs.
### tutorJS.ID
Returns the DOM object for the element with the passed id.
```javascript
var el = tutorJS.ID('myId');
```
### tutorJS.EL
Returns the DOM object for the element with the passed jQuery-like selector (only the first found).
```javascript
var el = tutorJS.EL('.myClass > someTag');
```
### tutorJS.ELS
Returns an array with the DOM objects for the elements with the passed jQuery-like selector.
```javascript
var els = tutorJS.ELS('.myClass > someTag');
```
### tutorJS.extend
Returns the new object extended by another.
```javascript
var obj = tutorJS.extend(obj1, obj2);
```
### tutorJS.attr
Adds attributes to the element from the passed object.
```javascript
var el = tutorJS.attr(tutorJS.EL('input'), {
required: 'required',
placeholder: 'Required input!',
});
```
### tutorJS.offset
Returns an offset of the element relative to the window (in px).
```javascript
var offset = tutorJS.offset(element);
var offTop = offset.top;
```
### tutorJS.width
Returns width of the element (in px).
```javascript
var elementWidth = tutorJS.width(element);
```
### tutorJS.height
Returns height of the element (in px).
```javascript
var elementHeight = tutorJS.height(element);
```
### tutorJS.positionTop
Returns the top offset of the element related to the document (in px).
```javascript
var elementTop = tutorJS.positionTop(element);
```
### tutorJS.scrolledTop
Returns number of the scrolled pixels (from the top of the document).
```javascript
var scr = tutorJS.scrolledTop();
```
### tutorJS.animateScroll
Scrolls to the passed position with animation (vertically).
```javascript
tutorJS.animateScroll(position, callback);
```
### tutorJS.isInView
Checks if specified element is fully visible on the page (only vertically).
```javascript
var isInView = tutorJS.isInView(element);
```
### tutorJS.on
Calls specified callback when an event fired on the element. Supports chaining.
```javascript
tutorJS.on(element, 'click', callback).on(element2, 'mouseover', callback2);
```
---
### tutorJS.create
Creates new SVG element tag or node if specified the second argument. Only SVG tags!
```javascript
var newCircle = tutorJS.create('circle');
var newNode = tutorJS.create('My special text', true);
```
### tutorJS.anim
Animates SVG element via adding animate tag. Just pass the special object with the parameters (`{attr: <>, to: <>, dur: <>}`). Supports chaining. Only for SVG!
```javascript
tutorJS
.anim(element, { attr: 'opacity', to: 1, dur: 300 }, callback1)
.and({ attr: 'height', to: '200px', dur: 1000 }, callback2)
.anim(anotherElement, { attr: 'width', to: '100px', dur: 500 }, callback3);
```