mithril-tour-component/README.md

Tour Guide Component for Mithril.js

# Mithril Tour Component

Tour Guide Component for [Mithril.js][mithril]

[![version][npm-version]][npm-url]
[![License][npm-license]][license-url]
[![Downloads][npm-downloads]][npm-url]
[![Dependencies][david-image]][david-url]

## Install

- Download [the latest package][download]
- NPM: `npm install mithril-tour-component`
- Browser: Use [build/tour.js](build/tour.js) or [build/tour.min.js](build/tour.min.js)

## Usage

**Node.js / Browserify**

```js
var m = require('mithril')
var TourComponent = require('mithril-tour-component')
```

**Note:** [lib/styles/tour.css](lib/styles/tour.css) is also required.

**Browser**

```html
<link href="path/to/mithril-tour-component/lib/styles/tour.css" rel="stylesheet" />
<script src="path/to/mithril.js" type="text/javascript"></script>
<script src="path/to/mithril-tour-component/build/tour.min.js" type="text/javascript"></script>
```

## Documentation

### TourComponent

Creates and returns a component class constructor which takes two arguments:

```js
Function TourComponent (Object options, Array Indicators)
```

#### Options

- `skipped` - *Boolean* - Disable rendering of indicators completely.
- `dismissed` - *Array* - Array of indicators that have been skipped. Useful for those *remembering where the user is* occasions.
- `onskip` - *Function(event, identifier)* - Global skip handler
- `ondismiss` - *Function(event, identifier)* - Global dismiss handler

Example:

```js
var dismissed = [1]
var skipped = false

TourComponent({
  skipped: skipped,
  dismissed: dismissed,

  ondismiss: function (event, identifier) {
    dismissed.push(identifier)
    // save to localstorage, etc.
  },

  onskip: function (event, identifier) {
    skipped = true
    // save to localstorage, etc.
  }
}, /* ... Indicators ... */)
```

#### Indicators

Each indicator is an `Object` that contains `properties` the properties of an Indicator are as follows:

- `id` - *Number / String* - Indicator / Tooltip identifier, **Optional**
- `x` - *Number* - x position on the page, **Optional when using `.element`**
- `y` - *Number* - y position on the page, **Optional when using `.element`**
- `element` - *Object* - Attach indicator to element
- `element.selector` - *String* - Target element selector
- `element.position` - Possible options include: `right, left, bottom right, bottom left, top right, top left, top, bottom`
- `element.offset` - *Object* - `x` and `y` offsets, **Optional**
- `ondismiss` - *Function(event, identifier)* - When a tooltip / indicator is dismissed (removed from page)
- `onclick` - *Function(event, identifier)* - When the indicator is clicked on.
- `onskip` - *Function(event, identifier)* - When the tour is completely skipped (all indicators are removed.)
- `onclose` - *Function(event, identifier)* - When the tooltip backdrop is closed (not considered dismissing / confirming)
- `tooltip` - *Object* - Tooltip settings
- `tooltip.content` - *Array* - Mithril children placed in the content section of the tooltip
- `tooltip.footer` - *Object* - Tooltip footer settings
- `tooltip.footer.skipText`
- `tooltip.footer.skipLinkText`
- `tooltip.footer.dismissText`

Example:

```js
TourComponent(/* ... options ... */, [{
  id: 1, // optional

  element: {
    selector: '.rotate-button',
    position: 'right',

    // Offset defaults
    offset: {
      x: 5,
      y: 10
    }
  },

  tooltip: {
    content: [
      m('p', 'Rotate list of links when clicked, give it a whirl!')
    ],

    footer: {
      skipText: 'Been here before? ',
      skipLinkText: 'Yes, disable tour!',
      dismissText: 'Thanks!'
    }
  }
}])
```

### Example Usage

[See index.html](index.html)

## Building

1. `npm install -g browserify uglify-js`
2. `npm run build`

## License

Licensed under [The MIT License](LICENSE).

[license-url]: https://github.com/Nijikokun/mithril-tour-component/blob/master/LICENSE

[npm-url]: https://www.npmjs.com/package/mithril-tour-component
[npm-license]: https://img.shields.io/npm/l/mithril-tour-component.svg?style=flat
[npm-version]: https://img.shields.io/npm/v/mithril-tour-component.svg?style=flat
[npm-downloads]: https://img.shields.io/npm/dm/mithril-tour-component.svg?style=flat

[david-url]: https://david-dm.org/Nijikokun/mithril-tour-component
[david-image]: https://img.shields.io/david/Nijikokun/mithril-tour-component.svg?style=flat

[download]: https://github.com/Nijikokun/mithril-tour-component/archive/v1.0.2.zip
[mithril]: https://github.com/lhorie/mithril.js