{"id":15395047,"url":"https://github.com/goto-bus-stop/sideshow","last_synced_at":"2025-07-21T21:34:31.103Z","repository":{"id":66054270,"uuid":"85726127","full_name":"goto-bus-stop/sideshow","owner":"goto-bus-stop","description":"An npm-friendly fork of the fantastic fortesinformatica/sideshow tutorial library.","archived":false,"fork":false,"pushed_at":"2018-07-19T07:10:19.000Z","size":9042,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-23T11:51:17.923Z","etag":null,"topics":["tutorial","wizard"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goto-bus-stop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-21T16:21:12.000Z","updated_at":"2020-04-01T18:11:39.000Z","dependencies_parsed_at":"2023-11-01T01:15:10.083Z","dependency_job_id":null,"html_url":"https://github.com/goto-bus-stop/sideshow","commit_stats":{"total_commits":134,"total_committers":11,"mean_commits":"12.181818181818182","dds":0.3955223880597015,"last_synced_commit":"770cb6f8b022bf35b97404a3a6c9dd54062f9389"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/goto-bus-stop/sideshow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goto-bus-stop%2Fsideshow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goto-bus-stop%2Fsideshow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goto-bus-stop%2Fsideshow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goto-bus-stop%2Fsideshow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goto-bus-stop","download_url":"https://codeload.github.com/goto-bus-stop/sideshow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goto-bus-stop%2Fsideshow/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266383521,"owners_count":23920919,"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","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["tutorial","wizard"],"created_at":"2024-10-01T15:25:28.969Z","updated_at":"2025-07-21T21:34:31.066Z","avatar_url":"https://github.com/goto-bus-stop.png","language":"JavaScript","readme":"# @goto-bus-stop/sideshow\n\n![Sideshow Logo](./examples/images/sideshow-logo.png)\n========\n[![Node.js devDependency Status](https://david-dm.org/goto-bus-stop/sideshow/dev-status.svg)](https://david-dm.org/goto-bus-stop/sideshow#info=devDependencies)\n[![License](http://img.shields.io/badge/license-Apache_2.0-red.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n\n[Documentation and Live example](http://fortesinformatica.github.io/Sideshow)\n\n[Install](#install) -\n[Usage](#usage) -\n[Configuration](#configuration) -\n[Creating a Tutorial](#creating-a-tutorial) -\n[Invoking Sideshow](#invoking-sideshow) -\n[License](#license-and-copyright)\n\nSideshow is a powerful javascript library which aims to reduce your user's\nlearning curve by providing a way to create step-by-step interactive helps.\n\n * Explain the features of your application\n * Control your end-user's interaction with your UI\n * Use Markdown to create formatted step descriptions\n * Emphasize what you're explaining in each step (a button, grid, dropdown,\n   form, the whole screen, and so forth) by surrounding it with a fully\n   adaptable mask.\n\n## Install\n\n```bash\nnpm install --save @goto-bus-stop/sideshow\n```\n\n## Usage\n\nWith CommonJS (like in Browserify) do:\n\n```js\nconst Sideshow = require(\"@goto-bus-stop/sideshow\");\n```\n\nAnd include the CSS somehow. [Sheetify](https://github.com/stackcss/sheetify) is good:\n\n```js\nconst css = require(\"sheetify\");\ncss(\"@goto-bus-stop/sideshow\");\n```\n\nWith ES Modules (like in Webpack or Rollup) do:\n\n```js\nimport Sideshow from \"@goto-bus-stop/sideshow\";\n```\n\nAnd include the CSS somehow. In Webpack with [css-loader](https://github.com/webpack/css-loader)\nthis works:\n\n```js\nimport \"@goto-bus-stop/sideshow/distr/sideshow.css\";\n```\n\nIn plain HTML without a bundler, do:\n\n```html\n\u003c!-- In the head: --\u003e\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/@goto-bus-stop/sideshow/distr/sideshow.min.css\"\u003e\n\n\u003c!-- In the body: --\u003e\n\u003cscript src=\"https://unpkg.com/@goto-bus-stop/sideshow/distr/sideshow.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // `Sideshow` is available!\n  Sideshow.init();\n\u003c/script\u003e\n```\n\n## Configuration\n\nOptionally configure Sideshow before calling `Sideshow.init()`:\n\n```js\n// Defaults:\nSideshow.config.language = \"en\";\nSideshow.config.autoSkipIntro = false;\n\nSideshow.init();\n```\n\n**Note**: For now, Sideshow only supports `en` (American English), `pt-br`\n(Brazilian Portuguese), `es` (Spanish, translated by Luis Alfaro de la Fuente,\nthanks!) and `fr` (French).\n\n## Creating a Tutorial\n\n```js\nSideshow.registerWizard({\n  name: \"introducing_sideshow\",\n  title: \"Introducing Sideshow\",\n  description: \"Introducing the main features and concepts of Sideshow. \",\n  estimatedTime: \"10 Minutes\",\n  affects: [\n    // This tutorial would be eligible for URLs like \"http://www.foo.com/bar#messages\"\n    { hash: \"#messages\" },\n    // This tutorial would be eligible for URLs like \"http://www.foo.com/adm/orders\"\n    { route: \"/adm/orders\", caseSensitive: true },\n    // Here we could do any checking to infer if this tutorial is eligible the current screen/context.\n    // After this checking, just return a boolean indicating if this tutorial will be available.\n    () =\u003e $(\".grid\").length \u003e 0\n  ]\n});\n```\n\n### Defining a Storyline\nA storyline is the sequence of steps of some tutorial.\n\n```js\nSideshow.registerWizard({\n  //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"Hello Sideshow.\",\n      text: \"This is an oversimplified example.\"\n    },\n    {\n      title: \"The end\",\n      text: \"What a pity =(.\"\n    }\n  ]\n});\n```\n\n### Step: A complete example\n\n```js\nSideshow.registerWizard({\n  //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"The log out button.\",\n      text: \"Click this button if you want to log out of the system.\",\n      subject: \"#user_details_panel\",\n      targets: \"#user_details_panel \u003e .logout\"\n    }\n  ]\n});\n```\n\n### Using Markdown\n\n```js\nSideshow.registerWizard({\n  //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"Markdown is pretty cool!\",\n      text: \"This step uses [Markdown](http://en.wikipedia.org/wiki/Markdown) for **text formatting**.\",\n      format: \"markdown\"\n    }\n  ]\n});\n```\n\n### Completing Conditions\nCompleting conditions are conditions to be satisfied in order to proceed to the next step.\n\n```js\nSideshow.registerWizard({\n    //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"Choose a name for your project\",\n      text: \"Enter a name for your project.\",\n      completingConditions: [\n        () =\u003e $(\"#project_name\").val().length \u003e 5\n      ]\n    },\n    //...\n  ]\n});\n```\n\n### Auto continue\nBy setting the autoContinue flag to true, Sideshow proceeds automaticaly when the completing conditions are satisfied.\n\n```js\nSideshow.registerWizard({\n    //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"Choose a name for your project\",\n      text: \"Enter a name for your project.\",\n      completingConditions: [\n        () =\u003e $(\"#project_name\").val().length \u003e 5\n      ],\n      autoContinue: true\n    },\n    //...\n  ]\n});\n```\n\n### Events\nYou can perform some action or do some preparation for the next step, or anything you want which can be done programatically.\n\n```js\nSideshow.registerWizard({\n  //...\n  listeners: {\n    beforeWizardStarts() {\n      //What goes here will be executed before the first step of this tutorial\n    },\n    afterWizardEnds() {\n      //What goes here will be executed after the last step of this tutorial\n    }\n  }\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      title: \"Foo bar\",\n      text: \"An example of step just to illustrate how to use step events.\",\n      listeners: {\n        beforeStep(){\n          //What goes here will be executed before this step\n        },\n        afterStep(){\n          //What goes here will be executed after this step\n        }\n      }\n    },\n    //...\n  ]\n});\n```\n\n### Skipping a step\n\nWhen entering some step you can do some verification to skip the step\nautomatically.\n\n```js\nSideshow.registerWizard({\n  //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      //...\n      skipIf: () =\u003e $(\"#groups\").children().length \u003e 0\n    },\n    //...\n  ]\n});\n```\n\n### Jumping to other step\nYou can jump to other step by its position (1-based) or its unique name.\n\n```js\nSideshow.registerWizard({\n    //...\n}).storyLine({\n  showStepPosition: true,\n  steps: [\n    {\n      //...\n      listeners: {\n        beforeStep(){\n          if ($(\"#groups\").children().length \u003e 0) {\n            Sideshow.gotoStep(\"the_end\"); //we're jumping to the step named \"the_end\"\n          } else if ($(\"#people\").children().length \u003e 0) {\n            Sideshow.gotoStep(7); //we're jumping to the seventh step in this Wizard storyline\n          }\n        }\n      }\n    },\n    //...\n    {\n      name: \"the_end\",\n      title: \"The end\",\n      //...\n    }\n  ]\n});\n```\n\n### Tutorial Eligibility\n\nWhen a user invokes Sideshow, a list with the tutorials available for the\ncurrent screen/context is shown. Sideshow knows if a tutorial is eligible for\nsome screen by testing the `affects` conditions of each registered tutorial. If\none of the conditions are met, the tutorial is listed.\n\n```js\nSideshow.registerWizard({\n  //...\n  affects: [\n    // This tutorial would be eligible for URLs like \"http://www.foo.com/bar#messages\"\n    { hash: \"#messages\" },\n    // This tutorial would be eligible for URLs like \"http://www.foo.com/adm/orders\"\n    { route: \"/adm/orders\", caseSensitive: true },\n    // Here we could do any checking to infer if this tutorial is eligible the\n    // current screen/context. After this checking, just return a boolean\n    // indicating if this tutorial will be available.\n    () =\u003e $(\".grid\").length \u003e 0\n  ]\n}).storyLine({\n  //...\n});\n```\n\n### Tutorial Preparation Function\n\nEven if a tutorial isn't eligible for some screen, by using a preparation\nfunction a user can access this tutorial from any point of your system/site (by\npressing shift-F2).\n\n\n```js\nSideshow.registerWizard({\n  // ...\n  preparation(doneCallback){\n    // if your app is a SPA, you could do some sort of redirection and call the\n    // doneCallback function after the page is loaded.\n  }\n}).storyLine({\n  // ...\n});\n```\n\n### Related Tutorials\n\nYou can also define relationships between tutorials, this way, after finishing a\ntutorial, the user sees a list of others related to this.\n\n\n```js\nSideshow.registerWizard({\n  // ...\n  // after finishing the current wizard, the user will be guided to related tutorials\n  relatedWizards: [\n    \"creating_user\",\n    \"groups_and_permissions\",\n    \"security_settings\"\n  ]\n}).storyLine({\n  //...\n});\n```\n\n### Skipping the Intro screen (the tutorial list) automatically if there's just one tutorial available for a given context\n\nIn the sideshow.config.js file, set the `autoSkipIntro` option to true:\n\n```js\nSideshow.config.autoSkipIntro = true;\n//...other configuration options\nSideshow.init();\n```\n\n## Invoking Sideshow\n\n *  The user can access the tutorials available for the current screen by\n    pressing `F2`.\n *  The user can access the tutorials available for the current screen +\n    tutorials for other screens with a preparation function by pressing\n    `shift+F2`.\n\n## Fortes Informática\n\nSideshow was created by [Fortes Informática](http://www.fortesinformatica.com.br),\na great technology company headquartered in Fortaleza, CE (Brazil). Fortes\nInformática has several offices across the country, and an impressive history of\nmore than 20 years. Sideshow is making our software yet more easy to use and\neven more innovative.\n\n## [License and Copyright](./LICENSE)\n\nCopyright 2013-2015 Fortes Informática\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoto-bus-stop%2Fsideshow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoto-bus-stop%2Fsideshow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoto-bus-stop%2Fsideshow/lists"}