{"id":13513728,"url":"https://github.com/easelinc/tourist","last_synced_at":"2025-10-22T16:16:54.476Z","repository":{"id":8286978,"uuid":"9825185","full_name":"easelinc/tourist","owner":"easelinc","description":"Simple, flexible tours for your app","archived":true,"fork":false,"pushed_at":"2018-10-11T04:33:53.000Z","size":990,"stargazers_count":1230,"open_issues_count":13,"forks_count":99,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-27T16:04:30.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://easelinc.github.io/tourist/","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/easelinc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-05-03T00:00:44.000Z","updated_at":"2024-04-08T12:39:59.000Z","dependencies_parsed_at":"2022-09-11T03:33:51.153Z","dependency_job_id":null,"html_url":"https://github.com/easelinc/tourist","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easelinc%2Ftourist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easelinc%2Ftourist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easelinc%2Ftourist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easelinc%2Ftourist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/easelinc","download_url":"https://codeload.github.com/easelinc/tourist/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222615147,"owners_count":17012022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T05:00:36.692Z","updated_at":"2025-10-22T16:16:49.105Z","avatar_url":"https://github.com/easelinc.png","language":"CoffeeScript","funding_links":[],"categories":["CoffeeScript","UI","Tours And Guides","Tours And Guides [🔝](#readme)","导览与指南"],"sub_categories":["Runner","运行器","运行器e2e测试"],"readme":"# Tourist.js [![Build Status](https://travis-ci.org/easelinc/tourist.png)](https://travis-ci.org/easelinc/tourist)\n\n\nTourist.js is a simple library for creating guided tours through your app.\nIt's better suited to complex, single-page apps than websites. One of our main\nrequirements was the ability to control the interface for each step. For\nexample, a step in the tour might need to open a window or menu to work\ncorrectly. Tourist gives you hooks to do this.\n\nBasically, you specify a series of steps which explain elements to point at\nand what to say. Tourist.js manages moving between those steps.\n\n### Install\n\nThe code is available via `bower install tourist`. Once you have the\ncode, you just need to include the javascript file. An optional CSS file\nwith minimal styling is included as well.\n\n```html\n\u003cscript src=\"tourist.js\"\u003e\u003c/script\u003e\n\n\u003c!-- Optional! --\u003e\n\u003clink rel=\"stylesheet\" href=\"tourist.css\" type=\"text/css\" media=\"screen\"\u003e\n```\n\n### Dependencies\n\nTourist depends on Backbone and jQuery. jQuery UI is optional. Tourist\nuses an easing function from jQuery UI if present in the show effect\nwith the Bootstrap tip implementation.\n\nTourist comes with the ability to use either [Bootstrap 3 popovers][popovers]\n(default) or [QTip2][qtip2] tips, so you'll need either Bootstrap 3 CSS\n(only the CSS is necessary!) or QTip2 installed.  You can write your own\ntooltip connector if you'd like.\n\n### Basic Usage\n\nMaking a simple tour is easy:\n\n```javascript\nvar steps = [{\n  // this is a step object\n  content: '\u003cp\u003eHey user, check this out!\u003c/p\u003e',\n  highlightTarget: true,\n  nextButton: true,\n  target: $('#thing1'),\n  my: 'bottom center',\n  at: 'top center'\n}, {\n  ...\n}, ...]\n\nvar tour = new Tourist.Tour({\n  steps: steps,\n  tipOptions:{ showEffect: 'slidein' }\n});\ntour.start();\n```\n\n# Reference\n\n## Tour object\n\nCreate one like this:\n\n```javascript\nvar steps = [{...}, {...}]\nvar tour = new Tourist.Tour({\n  steps: steps\n});\ntour.start();\n```\n\n### Options\n\n* `steps` a collection of step objects\n* `stepOptions` an object of options to be passed to each function called on a step object, notably the `setup()` and `teardown()` functions\n* `tipClass` the class from the `Tourist.Tip` namespace to use. Defaults to `Bootstrap`, you can use `QTip` if you have QTip2 installed\n* `tipOptions` an options object passed to the `tipClass` on creation\n* `cancelStep` step object for a step that runs if user hits the close button.\n* `successStep` step object for a step that runs last when they make it all the way through.\n\n### Methods\n\n* `start()` will start the tour. Can be used to restart a stopped tour\n* `stop(doFinalStep)` will stop the tour. doFinalStep is a bool; `true` will run the `cancelStep` specified in the options (if it's specified).\n* `next()` move to the next step\n\n## The step object\n\nThe 'step object' is a simple javascript object that specifies how a step will behave.\n\nA simple Example of a step object:\n\n```javascript\n{\n  content: '\u003cp\u003eWelcome to my step\u003c/p\u003e',\n  target: $('#something-to-point-at'),\n  closeButton: true,\n  highlightTarget: true,\n  setup: (tour, options) {\n    // do stuff in the interface/bind\n  },\n  teardown: function(tour, options) {\n    // remove stuff/unbind\n  }\n}\n```\n\n### Step object options\n\n* `content` a string of html to put into the step.\n* `target` jQuery object or absolute point: [10, 30]\n* `highlightTarget` optional bool, true will add the class `tour-highlight` to the target. If tourist.css is included, it will outline the target with a bright color.\n* `container` optional jQuery element that should contain the step flyout.\n              default: $('body')\n* `viewport` optional jQuery element that the step flyout should stay within.\n             $(window) is commonly used. default: false\n* `zIndex` optional string or number z-index value for the tip. If not specified, will use\n           value specified in css (or base tip implementation in case of QTip2 tips).\n           Value set on prev step will not affect later steps.\n* `my` string position of the pointer on the tip. default: 'left center'\n* `at` string position on the element the tip points to. default: 'right center' see http://craigsworks.com/projects/qtip2/docs/position/#basics\n* `okButton` optional bool, true will show a 'primary' ok button\n* `closeButton` optional bool, true will show a close button in the top right corner\n* `skipButton` optional bool, true will show a 'secondary' skip button\n* `nextButton` optional bool, true will show a 'primary' next button\n* `setup` optional function called before the tip is shown; see [setup](#setup) section\n* `teardown` optional function called when the tour moves to the next step; see [teardown](#teardown) section\n* `bind` optional list of function names to bind; see [bind](#bind) section\n\n### Step object function options\n\nAll functions on the step will have the signature `function(tour, options){}` where\n\n* `tour` is the Draw.Tour object. Handy to call tour.next()\n* `options` is the step options. An object passed into the tour when created.\n            It has the environment that the fns can use to manipulate the\n            interface, bind to events, etc. The same object is passed to all\n            of a step object's functions, so it is handy for passing data\n            between steps.\n\n#### setup()\n\n`setup()` is called before a step is shown. Use it to scroll to your\ntarget, hide/show things, etc.\n\n`this` is the step object itself.\n\n`setup()` can return an object. Properties in the returned object will override\nproperties in the step object.\n\nExample, the target might be dynamic so you would specify:\n\n```javascript\n{\n  setup: function(tour, options) {\n    options.model.bind('change:thing', this.onThingChange);\n    return { target: $('#point-to-me') };\n  }\n}\n```\n\n#### teardown()\n\n`teardown()` will be called right before hiding the step. Use to unbind from\nthings you bound to in setup().\n\n`this` is the step object itself.\n\n```javascript\n{\n  teardown: function(tour, options) {\n    options.model.unbind('change:thing', this.onThingChange);\n  }\n}\n```\n\nReturn nothing from `teardown()`\n\n#### bind\n\n`bind` is an array of function names to bind. Use this for event\nhandlers you use in `setup()`.\n\nWill bind functions to the step object as this, and the first 2 args as\ntour and options. i.e.\n\n```javascript\n{\n  bind: ['onChangeSomething'],\n  onChangeSomething: function(tour, options, model, value) {\n    tour.next()\n  },\n  setup: function(tour, options) {\n    options.document.bind('change:something', this.onChangeSomething);\n    return {};\n  },\n  teardown: function(tour, options) {\n    options.document.unbind('change:something', this.onChangeSomething)\n  }\n}\n```\n\n## Tip objects\n\nYou won't be creating `Tip` objects yourself, the `Tour` object will handle\nthat. But you can choose which tip implementation to use and you can pass the\ntip options to use on creation.\n\n### Bootstrap tips\n\nBootstrap tips are the default tip. They use only the markup and CSS from\nBootstrap. Bootstrap's javascript for tooltips or popovers is not necessary.\nHere's how to use them.\n\n```javascript\nvar tour = new Tourist.Tour({\n  steps: steps,\n  tipClass: 'Bootstrap'\n  tipOptions: {\n    showEffect: 'slidein'\n  }\n});\n```\n\nIt supports some options you can specify in `tipOptions`:\n\n* `showEffect` a string effect name\n* `hideEffect` a string effect name\n\nOnly one effect is defined at this time: `slidein`. And you need to include\njQuery UI to get the proper easing function for it.\n\nEffects are specified as functions on `Tourist.Tip.Bootstrap.effects`\ntake a look at the implementation for [an existing effect][booteffect] to get\nan idea how to extend.\n\n### QTip2 tips\n\nAn alternative is to use QTip2 tips. You need to include both the QTip\njavascript and CSS for these to work.\n\n```javascript\nvar tour = new Tourist.Tour({\n  steps: steps,\n  tipClass: 'QTip'\n  tipOptions: {\n    ...\n  }\n});\n```\n\nOptions accepted are any options QTip supports and in their format.\n\n### Your own Tip implementation\n\nYou can use your own tip implementation if you want. Make a class and\nhang it off the `Tourist.Tip` namespace. See [the tips code][tipscode]\nfor examples. The [bootstrap example][bootstraptip] is probably most\ninteresting. Here is a basic example in coffeescript:\n\n```coffeescript\n# you need to provide these implementations at a minimum\nclass Tourist.Tip.MyTip extends Tourist.Tip.Base\n  initialize: (options) -\u003e\n    # options would be: { likes: ['turtles'] }\n    $('body').append(@el)\n\n  show: -\u003e\n    @el.show()\n\n  hide: -\u003e\n    @el.hide()\n\n  _getTipElement: -\u003e\n    @el\n\n  # Jam the content into our element\n  _renderContent: (step, contentElement) -\u003e\n    @el.html(contentElement)\n\ntour = new Tourist.Tour\n  steps: steps\n  tipClass: 'MyTip'\n  tipOptions: { likes: ['turtles'] }\n```\n\n## Testing/Building\n\n* Requires grunt `npm install -g grunt-cli`\n* Install grunt modules `npm install`\n* Automatically compile changes `grunt watch`\n* Run tests with grunt `grunt test`\n\n## Browser support\n\nOfficially tested on latest Firefox and Chrome\n\n\n## Structure\n\n* /test/src - coffeescript jasmine tests\n* /test/suite - runs the tests\n* /src - coffeescript\n* tourist.js - generated js\n\n## Contributing\n\n* Adhere to our [styleguide][styleguide]\n* Send a pull request.\n* Write tests. New untested code will not be merged.\n\n## Release History\n\n* `major.minor.patch`: yyyy.mm.dd - description\n* `0.0.12`: 2013-06-12 - add zIndex step object option\n\nMIT License\n\n[jasmine]: http://pivotal.github.com/jasmine/\n[install]: http://jashkenas.github.com/coffee-script/#installation\n[skeleton]: http://buttersafe.com/2008/03/13/romance-on-the-floating-island/\n[styleguide]: https://github.com/easelinc/coffeescript-style-guide\n\n[qtip2]: http://craigsworks.com/projects/qtip2/\n[popovers]: http://getbootstrap.com/javascript/#popovers\n[booteffect]: https://github.com/easelinc/tourist/blob/master/src/tip/bootstrap.coffee#L64\n[tipscode]: https://github.com/easelinc/tourist/tree/master/src/tip\n[bootstraptip]: https://github.com/easelinc/tourist/blob/master/src/tip/bootstrap.coffee\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feaselinc%2Ftourist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feaselinc%2Ftourist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feaselinc%2Ftourist/lists"}