Tutorjs NPM | npm.io

1.3.1 • Published 1 year ago

Install

Weekly downloads

-

License

GPLV2

Repository

Last release

1 year ago

TutorJS

Interactive step-by-step tutorials with elements highlighting for your website, made with SVG.

Demo & examples

Browser compatibility

IE 9+
All other popular browsers

Dependences

None

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 <head> of your document:

<script type="text/javascript" src="js/tutor.min.js"></script>

Place code in the <body> of your document:

<svg
  id="tutorJS-svg"
  xmlns="http://www.w3.org/2000/svg"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  style="position: fixed; z-index: 100000; width:100%; height: 100%; cursor: default; top: 0; left: 0; display: none"
>
  ...
</svg>

Note: You can change svg styles as you like!

And just start your tutorial:

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.

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.

[
  {
    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.

{
  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).

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

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.

position: 'right';

Type: string Default: bottom Required: no

element.onActive

Function that would be called when this element would be highlighted.

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.

auto: 1000;

Type: number Default: 0 Required: no

options.onQuit

Function that is called on quitting active tutorial.

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.

bgQuit: false;

Type: boolen Default: true Required: no

options.showNext

Show the Next button or not.

showNext: false;

Type: boolen Default: true Required: no

options.showQuit

Show the Quit button or not.

showQuit: false;

Type: boolen Default: true Required: no

options.showCount

Show the pagination or not.

showCount: false;

Type: boolen Default: true Required: no

options.showHint

Show the hint block or not.

showHint: false;

Type: boolen Default: true Required: no

options.time

The average duration of animations and effects in ms (this actually is the factor).

time: 1000;

Type: number Default: 300 Required: no

quit

The method that quits your tutorial. No parametrs.

tutorJS.quit();

next

The method that shows the next step of your tutorial or quits it if no next step is available. No parametrs.

tutorJS.next();

recalc

Recalculates TutorJS elements positions (highlighting and the hint). No parameters.

tutorJS.recalc();

set

Reconfigures current tutorial options and the current element.

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)

var elements = tutorJS.elements;
var stepsN = elements.length;

Current element

var currentStep = tutorJS.activeEl;

Current step number

var stepN = tutorJS.active;

Instance options

var options = tutorJS.options;

TutorJS version

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.

var el = tutorJS.ID('myId');

tutorJS.EL

Returns the DOM object for the element with the passed jQuery-like selector (only the first found).

var el = tutorJS.EL('.myClass > someTag');

tutorJS.ELS

Returns an array with the DOM objects for the elements with the passed jQuery-like selector.

var els = tutorJS.ELS('.myClass > someTag');

tutorJS.extend

Returns the new object extended by another.

var obj = tutorJS.extend(obj1, obj2);

tutorJS.attr

Adds attributes to the element from the passed object.

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).

var offset = tutorJS.offset(element);
var offTop = offset.top;

tutorJS.width

Returns width of the element (in px).

var elementWidth = tutorJS.width(element);

tutorJS.height

Returns height of the element (in px).

var elementHeight = tutorJS.height(element);

tutorJS.positionTop

Returns the top offset of the element related to the document (in px).

var elementTop = tutorJS.positionTop(element);

tutorJS.scrolledTop

Returns number of the scrolled pixels (from the top of the document).

var scr = tutorJS.scrolledTop();

tutorJS.animateScroll

Scrolls to the passed position with animation (vertically).

tutorJS.animateScroll(position, callback);

tutorJS.isInView

Checks if specified element is fully visible on the page (only vertically).

var isInView = tutorJS.isInView(element);

tutorJS.on

Calls specified callback when an event fired on the element. Supports chaining.

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!

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!

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);

@everything-registry/sub-chunk-2987

1 year ago