Skip to content

Commit

Permalink
v0.3.0 major change - backdropOptions
Browse files Browse the repository at this point in the history
Major change implemented, new method to manage backdrop and highlight
  • Loading branch information
IGreatlyDislikeJavascript authored Oct 26, 2019
1 parent 40a0c87 commit 35c30d9
Show file tree
Hide file tree
Showing 3 changed files with 1,040 additions and 245 deletions.
103 changes: 92 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,27 @@ Tourist works with Bootstrap 3 and 4 (specify "framework" option), however the "

## Changelog from previous version:

Changes IN v0.2.0:
- Version update as major fix to bug preventing element: function(){...} feature under BS4/popper.js
- published as release
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!
Expand Down Expand Up @@ -104,6 +119,10 @@ The entire purpose of Tourist is to add features and fixes, and migrate to nativ
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

## Added features & fixes: Documentation
Full feature documentation below. These supersede any features or structure required by Bootstrap Tour.
Expand Down Expand Up @@ -663,17 +682,79 @@ var tour = new Tour({
You may specify only the labels you want to change. Unspecified labels will remain at their defaults:

```
var tour = new Tour({
localization:
{
buttonTexts: {
endTourButton: 'Adios muchachos'
}
}
});
var tour = new Tour({
localization:
{
buttonTexts: {
endTourButton: 'Adios muchachos'
}
}
});
```


### Always show the tour step even if the element doesn't exist, using showIfUnintendedOrphan
With thanks to @diesl

If a tour step specifies an element, and the element doesn't exist, showIfUnintendedOrphan will show the tour step as an orphan. This ensures
your tour step will always be shown.

delayOnElement takes priority over showIfUnintendedOrphan. I.e.: if you specify both delayOnElement and showIfUnintendedOrphan, the delay will timeout
before the step will be shown as an orphan.

This option is available globally and per step.

```
var tourSteps = [
{
element: "#btnSomething",
showIfUnintendedOrphan: true,
title: "Always",
content: "This tour step will always appear, either against element btnSomething if it exists, or as an orphan if it doesn't"
},
{
element: "#btnSomethingElse",
showIfUnintendedOrphan: true,
delayOnElement: {
delayElement: "element" // use string literal "element" to wait for this step's element, i.e.: #btnSomethingElse
},
title: "Always after a delay",
content: "This tour step will always appear. If element btnSomethingElse doesn't exist, delayOnElement will wait until it exists. If delayOnElement times out, step will show as an orphan"
},
{
element: "#btnDoesntExist",
showIfUnintendedOrphan: true,
title: "Always",
content: "This tour step will always appear",
onElementUnavailable: function() { console.log("this will never get called as showIfUnintendedOrphan will show step as an orphan"); }
},
]
```


### Customizable transitions for backdrop and highlight between tour steps
With huge thanks to @ibastevan, who provided a lot of the code and input to getting this working. Read more here:
https://github.com/IGreatlyDislikeJavascript/bootstrap-tourist/pull/24

Tourist now uses overlays to highlight tour step elements. A single backdrop div provides the dark/black background, and a highlight div is used
to highlight the element of a tour step. Each tour step element is then adjusted by zindex to pop to the top.

A new set of options called backdropOptions has been added globally, and can be overridden per step. This option could be considered not exactly simple
to understand! Please read the documentation at the top of bootstrap-tourist.js, which includes a full description of the options and examples on how to use them.

This option can be used to implement the following features:
- Fancy transitions between tour steps
- Use of 3rd party plugins such as animate.css for better UX
- Handling of rotated and transformed tour step elements
- Intelligent "sign-posting" of tour step elements

And much more. Essentially, you can manipulate the backdrop, highlight and tour step in any way you require by specifying your own functions and using
the Tourist helpers.





## Contributing
Feel free to contribute with pull requests, bug reports or enhancement suggestions.

Expand Down
96 changes: 63 additions & 33 deletions bootstrap-tourist.css
Original file line number Diff line number Diff line change
@@ -1,66 +1,96 @@
/* ========================================================================
* Bootstrap Tourist v0.7
* Bootstrap Tourist
* Copyright FFS 2019
* @ IGreatlyDislikeJavascript on Github
*
* bootstrap-tour - v0.11.0
* http://bootstraptour.com
* ========================================================================
* Copyright 2012-2015 Ulrich Sossou
*
* ========================================================================
* Licensed under the MIT License (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://opensource.org/licenses/MIT
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* ========================================================================
* z indexes:
* 1110 - backdrop (black bg)
* 1111 - highlight & tour element ()set by js)
* 1112 - prevent
* 1113 - popover
*/

.tour-backdrop {
.tour-backdrop {
top: 0;
bottom: 0;
left: 0;
right: 0;
/*position: fixed;*/
position: absolute;
z-index: 1100;
box-sizing: content-box;
z-index: 1110;
background-color: #000;
opacity: 0.8;
filter: alpha(opacity=80);
-ms-filter: "alpha(opacity=90)";
filter: alpha(opacity=90);
}

.tour-backdrop-animation {
-webkit-transition: all .3s ease-out;
-moz-transition: all .3s ease-out;
-ms-transition: all .3s ease-out;
-o-transition: all .3s ease-out;
transition: all .3s ease-out;
}

.tour-prevent {
position: absolute;
z-index: 1102;
background-color: #ccc;
z-index: 1112;
opacity: 0.20;
filter: alpha(opacity=20);
}
.popover[class*="tour-"] {

.tour-highlight {
box-sizing: content-box;
position: absolute;
z-index: 1110;
background-color: #FFF;
background-color: rgba(255,255,255,.9);
}

.tour-highlight-animation {
-webkit-transition: all .3s ease-out;
-moz-transition: all .3s ease-out;
-ms-transition: all .3s ease-out;
-o-transition: all .3s ease-out;
transition: all .3s ease-out;
}

.tour-highlight-element {
position: relative;
z-index: 1111 !important;
}

.popover[class*="tour-"] {
z-index: 1113;
}

.popover[class*="tour-"] .popover-navigation {
padding: 9px 14px;
overflow: hidden;
padding: 9px 14px;
overflow: hidden;
}

.popover[class*="tour-"] .popover-navigation *[data-role="end"] {
float: right;
float: right;
}

.popover[class*="tour-"] .popover-navigation *[data-role="prev"],
.popover[class*="tour-"] .popover-navigation *[data-role="next"],
.popover[class*="tour-"] .popover-navigation *[data-role="end"] {
cursor: pointer;
cursor: pointer;
}

.popover[class*="tour-"] .popover-navigation *[data-role="prev"].disabled,
.popover[class*="tour-"] .popover-navigation *[data-role="next"].disabled,
.popover[class*="tour-"] .popover-navigation *[data-role="end"].disabled {
cursor: default;
cursor: default;
}

.popover[class*="tour-"].orphan {
position: fixed;
margin-top: 0;
position: fixed;
margin-top: 0;
}

.popover[class*="tour-"].orphan .arrow {
display: none;
display: none;
}
Loading

0 comments on commit 35c30d9

Please sign in to comment.