Skip to content

Latest commit

 

History

History
132 lines (113 loc) · 3.45 KB

README.md

File metadata and controls

132 lines (113 loc) · 3.45 KB
Raw

React Tourist

A library for in-app tour guide in React. Checkout the example page.

Creating a tour

import Tour from 'react-tourist';
const tourItems = [
  { component: 'ExampleDiv1', ref: 'header', content: 'Hello World!' },
  { component: 'ExampleDiv2', ref: 'header', content: 'Bye World!' }
];
const myTour = new Tour(tourItems);

Tour methods

Start (and automatically show tour)

myTour.start({
  _auto: true,
  cb: () => { alert('Tour completed!') }
});

Trigger next item programmatically. For custom ([See more](#Tour item)), the onDone prop is passed in to the element. You can use that as an alternative to trigger the next action.

myTour.next();

Reset

myTour.reset();

Go to step

myTour.goToStep(3);

Skip (ends the tour immediately). For custom ([See more](#Tour item)), the onSkip prop is passed in to the element. You can use that as an alternative to trigger the skip action.

myTour.skip();

Setting up React Components

Component displayName and refs are used to target the particular tour element.

Or es6

@myTour.withTour
class ExampleDiv1 extends React.Component {
  static displayName = 'EvampleDiv1'  //  This is important for production mode
  render: function(){
    return (
      <h4 ref='header'>Hello world div!</h4>
    );
  }
}
expoxt const ExampleDiv1;

Tour item

Can be either an object or a function with a callback

{
  component: 'ExampleDiv1',
  ref: 'header',
  content: 'Hello World!'
  getElement: function(refNode){ return React.findDOMNode(refNode).children[0]; }
  style:  Tour.IndicatorStyle.cover
}
function(cb){
  doWork().then(cb);
}

Tour item props

Properties of tour item object.

  • component: Display Name of React component
  • ref: React ref on the target element
  • content: String or React Component
    • For String, a component SimpleTourItem is provided to render the tour item
    • For React Compoent, 2 function props are passed in (onDone, onSkip). The functions can be used by your custom component to continue or skip the tour
  • style: An object containing React style ([See more](#Tour item prop style))
  • doNotScroll: Do not automatically scroll to indicator position
  • getElement: A function for customising the element to use for indicator
    • Sometimes you may want to use a particular children of a ref
{
  getElement: function(refComponent) {
    return React.findDOMNode(refComponent).children[0];
  }
}

Tour item prop style

Default ones are provided in Tour.IndicatorStyle. 3 styles are available: IndicatorStyle.cover, IndicatorStyle.box, IndicatorStyle.pulse

For IndicatorStyle.pulse, the position is assumed to be centered.

IndicatorStyle.makePulse('left', 'top') //  (`left`, `center`, `right` and `top`, `center`, `bottom`)

Default styles can be overwritten by your custom style props.

IndicatorStyle.cover.overwrite({background: 'orange'})

Besides the default ones, you can use your own style object. The style is applied to a div that will overlay the element.

{
  style: function (element){
    return {
      background: 'yellow',
      width: element.width + 'px'
      height: element.height/2 + 'px'
    };
  }
}

Dev Instructions

==============================

  • Init: npm install
  • Develop: npm run dev
  • Compile: npm run compile
  • Compile for production: npm run compile-prod
  • Deploy to gh-pages: npm run build-example