Fishing Tour

Overview

Hello world! Fishing Tour is a small client side library that facilitates the creation of feature tours or tutorials. There are two objects in this library, Tour, and Tips. The Tour class is used to create a feature tour that prevents your users from using your site until they finishing going though the tour. The Tips class creates little icons near html elements of your choice and users can click on these icons. Upon clicking on an icon, a small card will open up and display a custom hint. The main difference between the Tour and Tips classes is that a user can ignore a feature tour implemented by Tips, but cannot ignore a feature tour implemented by the Tour class. Below are ways to implement both the Tour and the Tips classes. If you have any suggestions or if you find a bug, feel free to contact me at sher.shah010@gmail.com.

Tour

Tips

For Static Pages

Set Up

Simply move the following files into your project: fishing-tour.js, fishing-tour.css.

HTML

<!-- in the header -->
<link href="path/to/fishing-tour.css" rel="stylesheet">
<script src="path/to/fishing-tour.js"></script>
<!-- end of body -->
<script src="tour_implementation.js"></script>

Include the first two lines of code inbetween the head tag. These are to load in the required css and javascript. Feel free to look into these files and edit them as you like. The last line should be inserted right before the closing html tag. This will hold your custom feature tour. It is important that this code runs after all the html is loaded.

JavaScript (tour_implementation.js)

let tour = new Tour();
tour.add({selector: "h1", info: "This is an example of a tour", position: "right"});
// add more tour steps
tour.start(0);

Here is an implementation of a Tour feature tour. The first line creates a tour object. Adding a tour step is done by called the addStep method and passing an object with the required keys and values. See the documentation for the details on this object. You can add as many tour steps as you want. The last line starts the feature tour.

For Angular-Based Sites

Installation

$ npm install fishing-tour

Adding Styles (styles.css)

@import '~../node_modules/fishing-tour/styles.css';

HTML (sample.component.html)

<h1>Hi there.</h1>

TypeScript (sample.component.ts)

import { Component, OnInit, AfterViewInit } from '@angular/core';
import { Tour } from 'fishing-tour';

@Component({
  selector: 'app-sample',
  templateUrl: './sample.component.html',
  styleUrls: ['./sample.component.css']
})
export class SampleComponent implements OnInit, AfterViewInit {

  constructor() { }

  ngOnInit() { }

  ngAfterViewInit() {
    let tips = new Tour();
    tips.add({selector: "h1", info: "hello world!", position: "bottom"});
    tips.start(0);
  }

}

The start method must be called in the ngAfterViewInit function because the DOM needs to load before the first tour step can be shown.

Documentation

Tour()

constructor

Creates a Tour object.

.add(stepObject)

method

Adds a new tour step. The stepObject must have the following properties.

selector - required - string - A css query selector of the DOM element that a tip should be assigned to.
info - required - string - The message in a tour box.
position - required - string - The position of the tour box relative to its selector. The possible values are "top", "left", "right", and "bottom".

.start(index)

method

Starts the feature tour. Ensure that the DOM loads before calling this method. The index indicates which tour step to start on.

For Static Pages

Set Up

Simply move the following files into your project: fishing-tour.js, fishing-tour.css.

HTML

<!-- in the header -->
<link href="path/to/fishing-tour.css" rel="stylesheet">
<script src="path/to/fishing-tour.js"></script>
<!-- end of body -->
<script src="tip_implementation.js"></script>

JavaScript (tip_implementation.js)

let tips = new Tips();
tips.add({selector: "h1", header: "Welcome", info: "This is an example of a tip", x: "0px", y: "0px", fn: function() { alert("hello world") }});
// add more tips
tips.start(0);

Here is an implementation of a Tips feature tour. The first line creates a tip object. Adding a tip is done by called the add method and passing an object with the required keys and values. See the documentation for the details on this object. You can add as many tips as you want. The last line starts the feature tour. The zero indicates that the first tip will be shown. If, instead of zero, a one was passed, then the second tip will be shown and the first tip would be ignored, etc.

For Angular-Based Sites

Installation

$ npm install fishing-tour

Adding Styles (styles.css)

@import '~../node_modules/fishing-tour/styles.css';

HTML (sample.component.html)

<h1>Hi there.</h1>

TypeScript (sample.component.ts)

import { Component, OnInit, AfterViewInit } from '@angular/core';
import { Tips } from 'fishing-tour';

@Component({
  selector: 'app-sample',
  templateUrl: './sample.component.html',
  styleUrls: ['./sample.component.css']
})
export class SampleComponent implements OnInit, AfterViewInit {

  constructor() { }

  ngOnInit() { }

  ngAfterViewInit() {
    let tips = new Tips();
    tips.add({selector: "h1", header: "hi", info: "hello world!", x: "200px", y: "20px"});
    tips.start(0);
  }

}

The start method must be called in the ngAfterViewInit function because the DOM needs to load before the first tip icon can be shown.

Documentation

Tips()

constructor

Creates a Tips feature tour object.

.add(tipObject)

method

Adds a new tip with the parameters passed by the tipObject. The tipObject must be defined as below.

selector - required - string - A css query selector of the DOM element that a tip should be assigned to. This element will be forced to have the following css style: position: relative.
header - required - string - The header for tip.
info - required - string - The main text in the tip.
x - required - string - Determines how far left the tip icon and tip box is loacted relative to the selector DOM element.
y - required - string - Determines how far from the top the tip icon and tip box is loacted relative to the selector DOM element.
fn - optional - function - A function that is called when some one clicks the big button on the tip. This function should not return anything nor will any parameter be passed to it.

.start(index)

method

Starts the feature tour. Ensure that this is called after the DOM has been loaded. The index is an integer that notes which tip to show when the feature tour starts. Zero corresponds to the first tip, one corresponds to the second, etc.