Tour functionality update

- Removed CSS file - Library now manually instantiates, returns control object - Added ability to set class on buttons - Added ability to configure tour on instantiation - Slight code cleanup - Added ability to set the default tour object index - Prefix now works across the board - Updated HTML demo with some commenting and new instantiation method - Updated readme with proper instructions on use and options
crash83k · Jun 22, 2017 · b80f30d · b80f30d
1 parent 3413f2d
commit b80f30d
Show file tree

Hide file tree

Showing 4 changed files with 266 additions and 256 deletions.
diff --git a/README.md b/README.md
@@ -15,53 +15,115 @@ This library lets you highlight DOMs on the page, and explain what their purpose
  - Recalculates positions after window resizes.
 
 ## Things To Do Still
- - Update the library to instantiate programmatically to allow load-time configuration
  - Update the location calculations to work better on Mobile/Small Screens
  - Add more configuration options for styling
- - Put the CSS in the JS to control/change the class prefixes
  - Allow overriding the tour's functions (next/prev/exit)
 
 ## How To Use
-There are currently 3 parts to this:
- - CSS
- - HTML
- - JS
-
-I'd recommend minifying the CSS and JS before using in production. The files aren't large, but 
+
+#### Prerequisites
+
+ - jQuery 3.x
+ - A modern browser that has CSS transitions and animations.
+ - (optional) Bootstrap 3.x/4.x
+
+**Note:** By default, there are Bootstrap 3.x/4.x classes used for the control links in the tour.
+If you want to use them, you'll need to include the Bootstrap style sheet in your HTML.
+Otherwise, you'll probably want to add some style classes for the links and set them 
+in the instantiation options.
+
+#### Instantiation and Options
+
+I'd recommend minifying the JS before using in production. The file isn't large, but 
 everything adds up.
 
-Obviously, include the CSS and JavaScript files in your HTML page. I put the CSS in the head 
-and put the JS script tag as one of the last items in the HTML Body.
+Obviously, include the JavaScript file in your HTML page. It's best practice to
+ put the JS script tag as one of the last items in the HTML Body.
+
+
+###### Basic Instantiation
+
+The Page Tour JS file should be included _after_ the jQuery library.
+
+**Note:** When the tour initializes, it appends a style tag and a number of CSS rules to the document body.
+ If the names of these rules conflict with your application's CSS, you can change the prefix used for the library.
+
+After the JS file has been included on the page, the library can be instantiated by calling the page tour function:
+ ```JavaScript 
+// Instantiate the actual page tour object.
+var PageTour;
+try {
+    PageTour = $.fn.PageTour();
+} catch (e) {
+    console.error('Cannot start page tour: ', e);
+}
+ ```
+
+###### Options
+
+You can instantiate the Page Tour with your own options:
+
+```JavaScript
+var PageTour = $.fn.PageTour({ /* options */ });
+```
+
+The following options are exposed:
+ - `prefix` - [string default: 'tour'] Use this to change the full prefix of the CSS and HTML data attributes
+ - `horizontalPadding` - [integer default: 20] - Used to add left/right padding to tour elements
+ - `verticalPadding` - [integer default: 5] - Used to add top/bottom padding to tour elements
+ - `generalPadding` - [integer default: 5] - Used to add padding to target and shadow elements
+ - `nextText` - [string default: 'Next'] - The text shown on the "next" link.
+ - `prevText` - [string default: 'Previous'] - The text shown on the "previous" link.
+ - `exitText` - [string default: 'Exit'] - The text shown on the "exit" link.
+ - `nextClass` - [string default: 'btn btn-primary'] - The class for the "next" link.
+ - `prevClass` - [string default: 'btn btn-default'] - The class for the "previous" link.
+ - `exitClass` - [string default: 'btn btn-danger'] - The class for the "exit" link.
+ - `defaultIndex` - [integer default: '9999'] - The default index of items without a manually set index.
+
 
 #### HTML Attributes
 
 In the HTML, for each DOM you want to add to the tour, you must add at least one attribute to the
-DOM:
- - "data-tour-title" : This attribute should be assigned the title of the DOM object tour stop.
+DOM: 
+ - `data-<prefix>-title`: This attribute should be assigned the title of the DOM object tour stop.
    - example: `<div data-tour-title="DIV DOM Object"></div>`
- - "data-tour-description" : This attribute should be assigned the description of what the tour item is.
+ - `data-<prefix>-description`: This attribute should be assigned the description of what the tour item is.
    - example: `<div data-tour-description="This is a DIV HTML object. It's used to be a container for other DOMs"></div>`
+
+**Note:** In our examples, the prefix is the default "tour" prefix.
 
 Both of these attributes can  (and really should) be used together. However, only one is necessary.
 
 #### Ordering Tour Stops
 
-To enforce an order of which tour items are stopped at, you can add an index attribute:
+To enforce an order of which tour items are stopped at, you can add the `data-<prefix>-index` attribute:
  - example: `<div data-tour-index="1"></div>`
 
 The tour items are ordered by the index in a general integer sort. So you can skip numbers if that makes
-things easy. The order will start at 0. I haven't tested it, but it's possible you can go into
-negative numbers.
+things easy. You can also use negative numbers.
 
-Items without an index are actually defaulted to an index of `9999`.
+Items without an index are actually defaulted to an index of `9999`, though that can be changed via the 
+`defaultIndex` option.
 
 #### Programmatically Controlling the Tour
 
-The tour assigns a window-scoped dict object as `PageTour` at initialization. The `PageTour` object has 4 publicly accessible methods:
+The tour assigns a window-scoped dict object as `PageTour` at initialization. The `PageTour` object has 4 publicly 
+accessible methods:
  - `.open()` - Opens the tour. If the tour has previously been opened, it will open from where it was left off.
  - `.next()` - Moves the tour on to the next tour item.
  - `.prev()` - Moves the tour back to the previous tour item.
  - `.exit()` - Closes the tour.
+ - `.rediscover()` - [deprecated] Rediscover any new DOMs on the page. This is not really necessary at all. Each time the tour is 
+ opened, the DOMs are rediscovered.
 
 The only method completely necessary for tour operation is the `.open()` method. This starts the tour.
 However, controls to proceed through the tour and exit the tour are displayed in the tour.
+
+Example:
+```JavaScript
+// Instantiate the tour:
+var PageTour = $.fn.PageTour();
+
+// Open the tour:
+PageTour.open();
+```
diff --git a/css/tour.css b/css/tour.css
diff --git a/index.html b/index.html
@@ -2,6 +2,7 @@
 <html lang="en-us">
 <head>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Page Tour Demo</title>
     <style>
         .city {
             float: left;
@@ -12,16 +13,17 @@
             border: 1px solid black;
         }
     </style>
-    <link rel="stylesheet"
-          href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
+    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
           integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
           crossorigin="anonymous">
-    <link href="css/tour.css" rel="stylesheet" type="text/css"/>
 </head>
 <body>
 
-<h1>Responsive Web Design Demo</h1>
+<!--/// Start of HTML Example ///-->
 
+<h1 data-tour-description="This is the title of the page." data-tour-index="-1">Responsive Web Design Demo</h1>
+<h3>Reference to the original responsive design demo
+    <a href="https://www.w3schools.com/html/html_responsive.asp">here</a>.</h3>
 <div id="locations">
     <div class="city">
         <h2>London</h2>
@@ -31,11 +33,12 @@ <h2>London</h2>
         <a href="#" data-tour-title="Link Button" class="btn btn-link">Boom!</a>
     </div>
 
-    <div class="city" data-tour-index="0" data-tour-title="Card Type (0)" data-tour-description="A card will usually be one of multiple similar type items on a page.">
+    <!-- I'm using index -10 here to show this item first. -->
+    <div class="city" data-tour-index="-10" data-tour-title="Card Type" data-tour-description="A card will usually be one of multiple similar type items on a page.">
         <h2>Paris</h2>
         <p>Paris is the capital of France.</p>
         <p>The Paris area is one of the largest population centers in Europe, with more than 12 million inhabitants.</p>
-        <a href="#" data-tour-index="1" data-tour-title="Primary Button (1)" data-tour-description="I need a longer description for what this thing does." class="btn btn-primary">Boomer!</a>
+        <a href="#" data-tour-index="1" data-tour-title="Primary Button" data-tour-description="I need a longer description for what this thing does." class="btn btn-primary">Boomer!</a>
     </div>
 
     <div class="city">
@@ -51,22 +54,43 @@ <h2>New York</h2>
         <p>New York is an important center for international diplomacy and has been described as the cultural and
             financial
             capital of the world.</p>
-        <a href="#" data-tour-title="Default Button (2)" data-tour-index="2" data-tour-description="This is used the most." class="btn btn-default">Boomieist!</a>
+        <a href="#" data-tour-title="Default Button" data-tour-index="2" data-tour-description="This is used the most." class="btn btn-default">Boomieist!</a>
     </div>
 </div>
 
-<div>
-    <button id="start-tour">Start Tour</button>
-    <br/>
-    <button id="add-city">Add City</button>
+<div style="clear:both; padding:20px; text-align: center">
+    <button id="start-tour" class="btn btn-primary">Start Tour</button>
+    &nbsp;
+    <button id="add-city" class="btn btn-default">Add City</button>
 </div>
 
+<!--/// End of HTML Example ///-->
+
+
+<!--/// Start of JavaScript Example ///-->
+
+<!-- Include jQuery 3.x -->
 <script src="https://code.jquery.com/jquery-3.2.1.min.js"
         integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
         crossorigin="anonymous"></script>
 
+<!-- Include the page tour library -->
 <script src="js/tour.js"></script>
+
+<!-- Instantiate the page tour library -->
+<script>
+  // Instantiate the actual page tour object.
+  var PageTour;
+  try {
+    PageTour = $.fn.PageTour();
+  } catch (e) {
+    console.error('Cannot start page tour: ', e);
+  }
+</script>
+
+<!-- Just some extra testing functionality -->
 <script>
+  // Script to add dynamic "cities" for testing.
   $('#start-tour').on('click', PageTour.open);
   $('#add-city').on('click', function () {
     if (locs.length > 0) {
@@ -78,15 +102,13 @@ <h2>New York</h2>
         $('<p></p>', {
           html : loc.p2,
           'data-tour-title' : 'City Description',
-          'data-tour-Description' : 'This box shows the description of the city.',
+          'data-tour-Description' : 'This box shows the description of the city.'
         })
       );
       $('#locations').append(city)
     }
   });
-</script>
 
-<script>
   // Test after load adding new elements.
   var locs = [
     {
@@ -99,10 +121,10 @@ <h2>New York</h2>
       p1 : 'Wonderland is situated behind a mirror.',
       p2 : 'If you ever wondered what life would be like on a permanent acid trip, Wonderland is for you.'
     }
-  ]
-
-
+  ];
 </script>
 
+<!--/// End of JavaScript Example ///-->
+
 </body>
 </html>