diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9deec6a --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +# Logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Dependency directories +node_modules/ + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..2f88269 --- /dev/null +++ b/.npmignore @@ -0,0 +1 @@ +/docs diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..09cec61 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,109 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +## [0.3.1] + +### Added + - Added .gitignore + - Added .npmignore + - Added package.json + - Created CHANGELOG + +### Changed + - Updated README + +### Removed + - Removed comments from bootstrap-tourist.js + +## [0.3.0] + +### Added + - Added `showIfUnintendedOrphan` to show a tour step as an orphan if its element doesn't exist, overriding `onElementUnavailable` + +### Changed + - New method of backdrop and highlight added, with major effort and code from [@ibastevan](https://github.com/ibastevan): + - Overlay divs and customizable transitions between tour steps, [read more here](https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/pull/24) + - In short, previous versions of Tourist (and original Tour) used 4 divs to bracket the tour step elements. Tourist now uses overlays to produce the same effect. This solves many problems and enables many new features, including customizable transitions between tour steps. + +## 0.2.1 + +### Changed + - `delayOnElement` option now waits for elements not yet created in the DOM (thanks to [@lukaszmn](https://github.com/lukaszmn)) + +## [0.2.0] + +### Fixed + - fix bug preventing `element: function(){...}` feature under BS4/popper.js + +## [0.0.12-beta]: + +### Fixed + - fixes to the button text change code and better prep for localization (thanks to [@DancingDad](https://github.com/DancingDad), [@thenewbeat](https://github.com/thenewbeat), [@bardware](https://github.com/bardware)) + - fixed css for BS4 progress text to correctly use float-right (thanks to [@macroscian](https://github.com/macroscian), [@thenewbeat](https://github.com/thenewbeat)) + +## [0.0.10-beta]: + +### Added + - added support for changing button texts (thanks to [@vneri](https://github.com/vneri)) + - added dummy `init()` to support drop-in replacement for Tour (thanks to [@pau1phi11ips](https://github.com/pau1phi11ips)) + +## 0.0.9-beta: + +### Added + - default params compatibility for IE + +### Changed + - major change to manipulation of BS4 popper.js for orphan steps + - change to implementation of backdrop + +### Removed + - `smartPlacement` option removed, deprecated + +### Fixed + - auto progress bar was killed in changes 0.7 -> 0.8 due to Bootstrap sanitizer, this is readded + +## 0.0.8-beta: + +### Changed + - Improved BS4 support and template switching. Changed options for framework vs template. + +### Fixed + - Fix in 0.0.7-beta didn't work for Bootstrap 4. This release is to ensure fully working popovers in BS4. Issue is that the Bootstrap CDN doesn't actually have the whitelist property, so developing against it is basically useless :( + +## 0.0.7-beta: + +### Fixed + - Fix breaking change in Bootstrap 3.4.1, fixes this issue: https://github.com/sorich87/bootstrap-tour/issues/723#issuecomment-471107788. Issue is caused by the BS sanitizer, to avoid this reoccurring the "sanitizeWhitelist:" and "sanitizeFunction:" global options added + +## 0.0.6-beta: + +### Added + - Added `onPreviouslyEnded()` callback: https://github.com/sorich87/bootstrap-tour/issues/720 + - Added selector to switch between bootstrap3 and bootstrap4 or custom template, thanks to: https://github.com/sorich87/bootstrap-tour/pull/643 + +### Fixed + - Fixed invalid call to debug in `showNextStep()` + +## 0.0.5-beta: + +### Added + - Added "unfix" for bootstrap selectpicker to revert zindex after step that includes this plugin + +### Changed + - Improved the background overlay and scroll handling, unnecessary work removed + +### Fixed + - Fixed issue with Bootstrap dialogs. Handling of dialogs is now robust + - Fixed issue with BootstrapDialog plugin: https://nakupanda.github.io/bootstrap3-dialog/ . See notes below for help. + + +[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.1...HEAD +[0.3.1]: https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/compare/v0.2.0...v0.3.0 +[0.2.0]: https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/compare/0.2.0...v0.2.0 +[0.0.12-beta]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.10-beta...0.2.0 +[0.0.10-beta]: https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/releases/tag/v0.10-beta diff --git a/README.md b/README.md index b665039..c23b731 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Bootstrap Tourist +# Bootstrap Tourist [![NPM Version](http://img.shields.io/npm/v/bootstrap-tourist.svg?style=flat)](https://www.npmjs.org/) Quick and easy way to build your product tours with Bootstrap Popovers for Bootstrap 3 and 4. @@ -9,139 +9,697 @@ The original Bootstrap Tour was written in coffeescript, and had a number of ope Tourist works with Bootstrap 3.4 and 4.3 (specify "framework" option), however the "standalone" non-Bootstrap version is not available -## Minimum Bootstrap / jquery requirements +## Minimum Bootstrap / jQuery requirements There are some bugs in earlier BS3 and BS4, and jquery versions, that cause problems with Tourist. Please use minimum Bootstrap 3.4.x or 4.3.x, jquery 3.3.1 to avoid. Earlier versions may work, but try for yourself. - -## Changelog from previous version: - -Changes in v0.3.0 -- MAJOR REVISION: new method of backdrop and highlight added, with major effort and code from @ibastevan. - -Full changelog can be found in the top of bootstrap-tourist.js - -v0.3.0 represents a significant change to Bootstrap Tourist. - -Tourist is still completely drop-in replacement compatible with original Tour, -however @ibastevan and @IGreatlyDislikeJavascript have made significant changes -to how the backdrop works. You can read the conversation here: -https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/pull/24 - -In short, previous versions of Tourist (and original Tour) used 4 divs to bracket -the tour step elements. - -From v0.3.0, Tourist now uses overlays to produce the same effect. This solves -many problems and enables many new features, including customizable transitions -between tour steps. - -There may be residual bugs from this change so please report them in -the repo! - ## Getting started with Bootstrap Tourist -Simply include bootstrap-tourist.js and bootstrap-tourist.css into your page. A minified version is not provided because the entire purpose of this repo is to enable fixes, features and native port to ES6. If you are uncomfortable with this, please use the original Bootstrap Tour! - -```html - -.... - -``` - -Next, set up and start your tour with some steps: -```javascript -var tour = new Tour({ - framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap - steps: - [ - { - element: "#my-element", - title: "Title of my step", - content: "Content of my step" - }, - { - element: "#my-other-element", - title: "Title of my step", - content: "Content of my step" - } - ] - }); - -// Start the tour - note, no call to .init() required -tour.start(); -``` +If you are new to Bootstrap Tourist, and don't have Bootstrap Tour working, it's as simple as doing the following: +1. Simply include bootstrap-tourist.js and bootstrap-tourist.css into your page: + ```html + + + ... + + + ``` +1. Next, set up and start your tour with some steps: + ```js + var tour = new Tour({ + framework: 'bootstrap3', // or "bootstrap4" depending on your version of bootstrap + steps: [ + { + element: '#my-element', + title: 'Title of my step', + content: 'Content of my step' + }, + { + element: '#my-other-element', + title: 'Title of my step', + content: 'Content of my step' + } + ] + }); + + // Start the tour - note, no call to .init() is required + tour.start(); + ``` + +**NOTE**: A minified version is not provided because the entire purpose of this repo is to enable fixes, features and native port to ES6. If you are uncomfortable with this, please use the original Bootstrap Tour! ## Switching from Tour to Tourist If you already have a working tour using Bootstrap Tour, and you want to move to Tourist (because it has some fixes etc), perform the following steps: - 1. Copy over the Tourist CSS and JS, include them instead of Bootstrap Tour -2. If you are using Bootstrap 4, add the following option to your initialization code: - -```framework: "bootstrap4"``` - -For example: - -``` -var tour = new Tour({ - name: "tourist", - steps:[...steps go here...], - debug: true, // you may wish to turn on debug for the first run through - framework: "bootstrap4", // set Tourist to use BS4 compatibility - }); -``` - -3. Remove the call to tour.init() - this is not required - -4. Add a call to tour.start() to start the tour, and optionally add a call to tour.restart() to force restart the tour - + - If you are using Bootstrap 4, add the `framework: 'bootstrap4'` option to your initialization code. + - Example: + ```js + const tour = new Tour({ + name: 'tourist', + steps: [...steps go here...], + debug: true, // you may wish to turn on debug for the first run through + framework: 'bootstrap4', // set Tourist to use BS4 compatibility + }); + ``` +1. Remove the call to `tour.init()` - this is not required +1. Add a call to `tour.start()` to start the tour, and optionally add a call to `tour.restart()` to force restart the tour ## Basic Demo and Documentation -Tourist now has documentation included in the repo /docs/ folder. Take a look! - -# Documentation note -In bootstrap-tourist.js, you will find comprehensive documentation and examples at the very top of the file. - -## Added features & fixes: Summary -The entire purpose of Tourist is to add features and fixes, and migrate to native ES6. Here is a list of all additional features and fixes in Tourist (compared to original Tour). All original Tour options are still available, unless superseded by the documentation below: - - 1. onNext/onPrevious - prevent auto-move to next step, allow .goTo - 2. *** Do not call Tour.init *** - fixed tours with hidden elements on page reload - 3. Dynamically determine step element by function - 4. Only continue tour when reflex element is clicked using reflexOnly - 5. Call onElementUnavailable if step element is missing - 6. Scroll flicker/continual step reload fixed - 7. Magic progress bar and progress text, plus options to customize per step - 8. Prevent user interaction with element using preventInteraction - 9. Wait for arbitrary DOM element to be visible before showing tour step/crapping out due to missing element, using delayOnElement - 10. Handle bootstrap modal dialogs better - autodetect modals or children of modals, and call onModalHidden to handle when user dismisses modal without following tour steps - 11. Automagically fixes drawing issues with Bootstrap Selectpicker (https://github.com/snapappointments/bootstrap-select/) - 12. Call onPreviouslyEnded if tour.start() is called for a tour that has previously ended (see docs) - 13. Switch between Bootstrap 3 or 4 (popover template) automatically using tour options - 14. Added sanitizeWhitelist and sanitizeFunction global options, fixed Bootstrap 3.4.1 breaking change - 15. Added support for changing button texts - -from v0.3.0: - - 16. Added showIfUnintendedOrphan to show a tour step as an orphan if its element doesn't exist, overriding onElementUnavailable - 17. Overlay divs and customizable transitions between tour steps - +Tourist now has documentation included in the repo under the `/docs/` folder. Take a look! +1. Control flow from `onNext()` / `onPrevious()` options: + - Returning false from onNext/onPrevious handler will prevent Tour from automatically moving to the next/previous step. + - Tour flow methods (Tour.goTo etc) now also work correctly in onNext/onPrevious. + - Option is available per step or globally: + ```js + var tourSteps = [ + { + element: "#inputBanana", + title: "Bananas!", + content: "Bananas are yellow, except when they're not", + onNext: function (tour) { + if ($("#inputBanana").val() !== "banana") { + + // no banana? highlight the banana field + $("#inputBanana").css("background-color", "red"); + + // do not jump to the next tour step! + return false; + } + } + } + ]; + + var tour = new Tour({ + steps: tourSteps, + framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap + buttonTexts: { // customize or localize button texts + nextButton: "go on", + endTourButton: "ok it's over", + }, + onNext: function(tour) { + if (someVar = true) { + // force the tour to jump to slide 3 + tour.goTo(3); + // Prevent default move to next step - important! + return false; + } + } + }); + ``` +1. Do not call `tour.init()`: + - When setting up Tour, do not call `tour.init()`. Call `tour.start()` to start/resume the Tour from previous step. Call `tour.restart()` to always start Tour from the first step + `tour.init()` was a redundant method that caused conflict with hidden Tour elements. + - As of Tourist v0.11, calling `tour.init()` will generate a warning in the console (thanks to [@pau1phi11ips](https://github.com/pau1phi11ips)). +1. Dynamically determine element by function: + - Step "element:" option allows element to be determined programmatically. Return a jquery object. The following is possible: + ```js + var tourSteps = [ + { + element: function () { + return $(document).find(".something"); + }, + title: "Dynamic", + content: "Element found by function" + }, + { + element: "#static", + title: "Static", + content: "Element found by static ID" + } + ]; + ``` +1. Only continue tour when reflex element is clicked: + - Use step option reflexOnly in conjunction with step option reflex to automagically hide the "next" button in the tour, and only continue when the user clicks the element: + ```js + var tourSteps = [ + { + element: "#myButton", + reflex: true, + reflexOnly: true, + title: "Click it", + content: "Click to continue, or you're stuck" + } + ]; + ``` +1. Call function when element is missing: + - If the element specified in the step (static or dynamically determined as per feature #3), `onElementUnavailable` is called. + - Function signature: `function(tour, stepNumber) {}` + - Option is available at global and per step levels: + - Use it per step to have a step-specific error handler: + ```js + function tourStepBroken(tour, stepNumber) { + alert("Uhoh, the tour broke on the #btnMagic element"); + } + + var tourSteps = [ + { + element: "#btnMagic", + onElementUnavailable: tourStepBroken, + title: "Hold my beer", + content: "now watch this" + } + ]; + ``` + - Use it globally, and optionally override per step, to have a robust and comprehensive error handler: + ```js + function tourBroken(tour, stepNumber) { + alert('The default error handler: tour element is done broke on step number ' + stepNumber); + } + + var tourSteps = [ + { + element: "#btnThis", + // onElementUnavailable: COMMENTED OUT, therefore default global handler used + title: "Some button", + content: "Some content" + }, + { + element: "#btnThat", + onElementUnavailable: function (tour, stepNumber) { + // override the default global handler for this step only + alert("The tour broke on #btnThat step"); + }, + title: "Another button", + content: "More content" + } + ]; + + var tour = new Tour({ + steps: tourSteps, + framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap + onElementUnavailable: tourBroken, // default "element unavailable" handler for all tour steps + }); + ``` +1. Scroll flicker / continue reload fixed: + - Original Tour constantly reloaded the current tour step on scroll & similar events. This produced flickering, constant reloads and therefore constant calls to all the step function calls. This is now fixed. Scrolling the browser window does not cause the tour step to reload. + - **IMPORTANT**: orphan steps are stuck to the center of the screen. However steps linked to elements ALWAYS stay stuck to their element, even if user scrolls the element & tour popover off the screen. This is my personal preference, as original functionality of tour step moving with the scroll even when the element was off the viewport seemed strange. +1. Customizable progress bar & text + 1. Progress bar & progress text: + - With thanks to [@macroscian](](https://github.com/macroscian), [@thenewbeat](](https://github.com/thenewbeat) for fixes to this code, incorporated in Tourist v0.12 + - Use the following options globally or per step to show tour progress: + - `showProgressBar`: shows a bootstrap progress bar for tour progress at the top of the tour content + - `showProgressText`: shows a textual progress (N/X, i.e.: 1/24 for slide 1 of 24) in the tour title + - example: + ```js + var tourSteps = [ + { + element: "#inputBanana", + title: "Bananas!", + content: "Bananas are yellow, except when they're not", + }, + { + element: "#inputOranges", + title: "Oranges!", + content: "Oranges are not bananas", + showProgressBar: false, // don't show the progress bar on this step only + showProgressText: false, // don't show the progress text on this step only + } + ]; + + var tour = new Tour({ + framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap + steps: tourSteps, + showProgressBar: true, // default show progress bar + showProgressText: true, // default show progress text + }); + ``` + 1. Customize the progressbar/progress text: + - In conjunction with 7a, provide the following functions globally or per step to draw your own progressbar/progress text: + - `getProgressBarHTML(percent)` + - `getProgressTextHTML(stepNumber, percent, stepCount)` + - These will be called when each step is shown, with the appropriate percentage/step number etc passed to your function. Return an HTML string of a "drawn" progress bar/progress text which will be directly inserted into the tour step. + - example: + ```js + var tourSteps = [ + { + element: "#inputBanana", + title: "Bananas!", + content: "Bananas are yellow, except when they're not", + }, + { + element: "#inputOranges", + title: "Oranges!", + content: "Oranges are not bananas", + getProgressBarHTML: function(percent) { + // override the global progress bar function for this step + return '
You\'re ' + percent + ' of the way through!
'; + } + } + ]; + + var tour = new Tour({ + steps: tourSteps, + showProgressBar: true, // default show progress bar + showProgressText: true, // default show progress text + getProgressBarHTML: function(percent) { + // default progress bar for all steps. Return valid HTML to draw the progress bar you want + return '
'; + }, + getProgressTextHTML: function(stepNumber, percent, stepCount) { + // default progress text for all steps + return 'Slide ' + stepNumber + "/" + stepCount; + } + }); + ``` +1. Prevent interaction with element + - Sometimes you want to highlight a DOM element (button, input field) for a tour step, but don't want the user to be able to interact with it. Use preventInteraction to stop the user touching the element: + ```js + var tourSteps = [ + { + element: "#btnMCHammer", + preventInteraction: true, + title: "Hammer Time", + content: "You can't touch this" + } + ]; + ``` +1. Wait for an element to appear before continuing tour: + - Sometimes a tour step element might not be immediately ready because of transition effects etc. This is a specific issue with bootstrap select, which is relatively slow to show the selectpicker dropdown after clicking. Use delayOnElement to instruct Tour to wait for **ANY** element to appear before showing the step (or crapping out due to missing element). Yes this means the tour step element can be one DOM element, but the delay will wait for a completely separate DOM element to appear. This is really useful for hidden divs etc. + - Use in conjunction with onElementUnavailable for robust tour step handling. + - `delayOnElement` is an object with the following: + ```js + delayOnElement: { + delayElement: "#waitForMe", // the element to wait to become visible, or the string literal "element" to use the step element, or a function + maxDelay: 2000 // optional milliseconds to wait/timeout for the element, before crapping out. If maxDelay is not specified, this is 2000ms by default, + } + ``` + - example: + ```js + var tourSteps = [ + { + element: "#btnPrettyTransition", + delayOnElement: { + delayElement: "element" // use string literal "element" to wait for this step's element, i.e.: #btnPrettyTransition + }, + title: "Ages", + content: "This button takes ages to appear" + }, + { + element: "#btnPrettyTransition", + delayOnElement: { + delayElement: function() { + return $("#btnPrettyTransition"); // return a jquery object to wait for, in this case #btnPrettyTransition + } + }, + title: "Function", + content: "This button takes ages to appear, we're waiting for an element returned by function" + }, + { + element: "#inputUnrelated", + delayOnElement: { + delayElement: "#divStuff" // wait until DOM element "divStuff" is visible before showing this tour step against DOM element "inputUnrelated" + }, + title: "Waiting", + content: "This input is nice, but you only see this step when the other div appears" + }, + { + element: "#btnDontForgetThis", + delayOnElement: { + delayElement: "element", // use string literal "element" to wait for this step's element, i.e.: #btnDontForgetThis + maxDelay: 5000 // wait 5 seconds for it to appear before timing out + }, + title: "Cool", + content: "Remember the onElementUnavailable option!", + onElementUnavailable: function(tour, stepNumber) { + // This will be called if btnDontForgetThis is not visible after 5 seconds + console.log("Well that went badly wrong"); + } + }, + ]; + ``` +1. Trigger when modal closes: + - If tour element is a modal, or is a DOM element inside a modal, the element can disappear "at random" if the user dismisses the dialog. + - In this case, onModalHidden global and per step function is called. Only functional when step is not an orphan. + - This is useful if a tour includes a step that launches a modal, and the tour requires the user to take some actions inside the modal before OK'ing it and moving to the next tour step: + - Return (int) step number to immediately move to that step + - Return exactly false to not change tour state in any way - this is useful if you need to reshow the modal because some validation failed + - Return anything else to move to the next step + - element === Bootstrap modal, or element parent === bootstrap modal is automatically detected. + - example: + ```js + var tour = new Tour({ + steps: tourSteps, + framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap + onModalHidden: function(tour, stepNumber) { + console.log("Well damn, this step's element was a modal, or inside a modal, and the modal just done got dismissed y'all. Moving to step 3."); + + // move to step number 3 + return 3; + }, + }); + + var tour = new Tour({ + steps: tourSteps, + onModalHidden: function(tour, stepNumber) { + if (validateSomeModalContent() == false) { + // The validation failed, user dismissed modal without properly taking actions. + // Show the modal again + showModalAgain(); + + // Instruct tour to stay on same step + return false; + } else { + // Content was valid. Return null or do nothing to instruct tour to continue to next step + } + }, + }); + ``` +1. Handle Dialogs and BootstrapDialog plugin better https://nakupanda.github.io/bootstrap3-dialog/ + - Plugin makes creating dialogs very easy, but it does some extra stuff to the dialogs and dynamically creates/destroys them. This causes issues with plugins that want to include a modal dialog in the steps using this plugin. + - To use Tour to highlight an element in a dialog, just use the element ID as you would for any normal step. The dialog will be automatically detected and handled. + - To use Tour to highlight an entire dialog, set the step element to the dialog div. Tour will automatically realize this is a dialog, and shift the element to use the modal-content div inside the dialog. This makes life friendly, because you can do this: + ```html + + ``` + - Then use element myModal in the Tour. + - **FOR BOOTSTRAPDIALOG PLUGIN**: + - This plugin creates random UUIDs for the dialog DOM ID. You need to fix the ID to something you know. Do this: + ```js + dlg = new BootstrapDialog.confirm({ + ...all the options... + }); + + // BootstrapDialog gives a random GUID ID for dialog. Give it a proper one + $objModal = dlg.getModal(); + $objModal.attr("id", "myModal"); + dlg.setId("myModal"); + ``` + - Now you can use element myModal in the tour, even when the dialog is created by BootstrapDialog plugin. +1. Fix conflict with Bootstrap Selectpicker: https://github.com/snapappointments/bootstrap-select/ + - Selectpicker draws a custom select. Tour now automagically finds and adjusts the selectpicker dropdown so that it appears correctly within the tour +1. Call `onPreviouslyEnded` if `tour.start()` is called for a tour that has previously ended: + - See the following github issue: https://github.com/sorich87/bootstrap-tour/issues/720 + - Original behavior for a tour that had previously ended was to call onStart() callback, and then abort without calling onEnd(). This has been altered so that calling start() on a tour that has previously ended (cookie step set to end etc) will now ONLY call onPreviouslyEnded(). + - This restores the functionality that allows app JS to simply call tour.start() on page load, and the Tour will now only call onStart() / onEnd() when + the tour really is started or ended. + - example: + ```js + var tour = new Tour({ + steps: [ ... ], + framework: "bootstrap3", // or "bootstrap4" depending on your version of bootstrap + onPreviouslyEnded: function(tour) { + console.log("Looks like this tour has already ended"); + }, + }); + + tour.start(); + ``` +1. Switch between Bootstrap 3 or 4 (popover methods, template) automatically using tour options, or use a custom template: + - With thanks to this thread: https://github.com/sorich87/bootstrap-tour/pull/643 + - Tour is compatible with bootstrap 3 and 4 if the right template and framework is used for the popover. Bootstrap3 framework compatibility is used by default. + - To select the correct template and framework, use the "framework" global option. Note this option does more than just select a template, it also changes which methods are used to manage the Tour popovers to be BS3 or BS4 compatible. + ```js + var tour = new Tour({ + steps: tourSteps, + template: null, // template option is null by default. Tourist will use the appropriate template for the framework version, in this case BS3 as per next option + framework: "bootstrap3", // can be string literal "bootstrap3" or "bootstrap4" + }); + ``` + - To use a custom template, use the "template" global option: + ```js + var tour = new Tour({ + steps: tourSteps, + framework: "bootstrap4", // can be string literal "bootstrap3" or "bootstrap4" + template: '' + }); + ``` + - Review the following logic: + - If template == null, default framework template is used based on whether framework is set to "bootstrap3" or "bootstrap4" + - If template != null, the specified template is always used + - If framework option is not literal "bootstrap3" or "bootstrap4", error will occur + - To add additional templates, search the code for "PLACEHOLDER: TEMPLATES LOCATION". This will take you to an array that contains the templates, simply edit or add as required. +1. Options to manipulate the Bootstrap sanitizer, and fix the sanitizer related breaking change in BS 3.4.x: + - BS 3.4.1 added a sanitizer to popover and tooltips - this breaking change strips non-whitelisted DOM elements from popover content, title etc. + - See: https://getbootstrap.com/docs/3.4/javascript/#js-sanitizer and https://blog.getbootstrap.com/2019/02/13/bootstrap-4-3-1-and-3-4-1/ + - This Bootstrap change resulted in Tour navigation buttons being killed from the DOM: https://github.com/sorich87/bootstrap-tour/issues/723#issuecomment-471107788 + - This has been fixed in code, Tour navigation buttons now appear and work by default. + - To prevent future similar reoccurrences, and also allow the manipulation of the sanitizer "allowed list" for Tours that want to add extra content into tour steps, two features added to global options. To understand the purpose and operation of these features, review the following information on the Bootstrap sanitizer: https://getbootstrap.com/docs/3.4/javascript/#js-sanitizer + - _**IMPORTANT NOTE** SECURITY RISK_: if you do not understand the purpose of the sanitizer, why it exists in bootstrap or how it relates to Tour, do not use these options. + - Global options: + - `sanitizeWhitelist`: specify an object that will be merged with the Bootstrap Popover default whitelist. Use the same structure as the default Bootstrap whitelist. + - `sanitizeFunction`: specify a function that will be used to sanitize Tour content, with the following signature: string function(content). Specifying a function for this option will cause sanitizeWhitelist to be ignored. Specifying anything other than a function for this option will be ignored, and sanitizeWhitelist will be used + - Examples: + - Allow tour step content to include a button with attributes `data-someplugin1="..."` and `data-somethingelse="..."`. Allow content to include a selectpicker. + ```js + var tour=new Tour({ + steps: tourSteps, + sanitizeWhitelist: { + "button" : ["data-someplugin1", "data-somethingelse"], // allows