Version 2.0.0 / Merge remote-tracking branch 'origin/dev'

pickhardt · Aug 6, 2013 · 41b66f3 · 41b66f3
2 parents e7ff5b2 + 50fb591
commit 41b66f3
Show file tree

Hide file tree

Showing 11 changed files with 391 additions and 187 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/README.html b/README.html
@@ -26,9 +26,9 @@
     </style>
 
     <!-- guiders.js requires jQuery as a prerequisite. Be sure to load guiders.js AFTER jQuery. -->
-    <script type="text/javascript" src="jquery-1.5.1.min.js"></script>
-    <script type="text/javascript" src="guiders-1.3.0.js"></script>
-    <link rel="stylesheet" href="guiders-1.3.0.css" type="text/css" />
+    <script type="text/javascript" src="jquery.min.js"></script>
+    <script type="text/javascript" src="guiders.js"></script>
+    <link rel="stylesheet" href="guiders.css" type="text/css" />
   </head>
   <body>
     <br />
@@ -56,6 +56,26 @@
     <br />
     <br />
     <br />
+
+    <!-- The following is an alternate way to create your guiders in the HTML itself -->
+    <!-- (This is new with version 2.0.0) -->
+    <div id="guider2" class="guider" data-attachTo="#clock" data-position="12">
+      <div class="guiders_content">
+        <h1 class="guiders_title">Guiders are typically attached to an element on the page.</h1>
+
+        <p class="guiders_description">
+          For example, this guider is attached to the 12 o'clock direction relative to the attached element. The Guiders.js API uses a clock model to determine where the guider should be placed.<br/><br/>Attaching a guider to an element focuses user on the area of interest.
+        </p>
+
+        <div class="guiders_buttons_container">
+          <div>Close</div>
+          <div>Next</div>
+        </div>
+      </div>
+
+      <div class="guiders_arrow"></div>
+    </div>
+
 
     <script type="text/javascript">
     /**
@@ -71,13 +91,16 @@
      * its onclick handler.  A button named "Close" will have
      * its onclick handler set to guiders.hideAll.  onclick handlers
      * can be customized too.
+     *
+     * An alternate method for creating guiders is to create them in the 
+     * HTML, then call $("#guider3").guider(options);
      */
 
     guiders.createGuider({
       buttons: [{name: "Next"}],
       description: "Guiders are a user interface design pattern for introducing features of software. This dialog box, for example, is the first in a series of guiders that together make up a guide.",
-      id: "first",
-      next: "second",
+      id: "guider1",
+      next: "guider2",
       overlay: true,
       title: "Welcome to Guiders.js!"
     }).show();
@@ -95,37 +118,31 @@
      * to route people among multiple web pages and still keep showing the guiders.
      */
 
-    guiders.createGuider({
-      attachTo: "#clock",
-      buttons: [{name: "Close"},
-                {name: "Next"}],
-      description: "For example, this guider is attached to the 12 o'clock direction relative to the attached element. The Guiders.js API uses a clock model to determine where the guider should be placed.<br/><br/>Attaching a guider to an element focuses user on the area of interest.",
-      id: "second",
-      next: "third",
-      position: 12,
-      title: "Guiders are typically attached to an element on the page."
+   // Alternate method of creating guiders allows you to keep the buttons and description in the HTML:
+   $("#guider2").guider({
+      next: "guider3"
     });
-               
-    guiders.createGuider({
+
+   guiders.createGuider({
       attachTo: "#clock",
       buttons: [{name: "Close, then click on the clock.", onclick: guiders.hideAll}],
       description: "Custom event handlers can be used to hide and show guiders. This allows you to interactively show the user how to use your software by having them complete steps. To try it, click on the clock.",
-      id: "third",
-      next: "fourth",
-      position: 2,
+      id: "guider3",
+      next: "guider4",
+      position: 3,
       title: "You can advance guiders from custom event handlers.",
       width: 500
     });
-
+    
     guiders.createGuider({
       attachTo: "#clock",
       buttons: [{name: "Exit Guide", onclick: guiders.hideAll},
                 {name: "Back"},
                 {name: "Continue", onclick: guiders.next}],
       buttonCustomHTML: "<input type=\"checkbox\" id=\"stop_showing\" /><label for=\"stop_showing\" class=\"stopper\">Optional checkbox. (You can add one.)</label>",
       description: "Other aspects of the guider can be customized as well, such as the button names, button onclick handlers, and dialog widths. You'd also want to modify the CSS to your own project's style.",
-      id: "fourth",
-      next: "fifth",
+      id: "guider4",
+      next: "guider5",
       position: 7,
       title: "Guiders can be customized.",
       width: 600
@@ -134,8 +151,8 @@
     guiders.createGuider({
       buttons: [{name: "Next"}],
       description: "Guiders can also be used to introduce of brand new features to existing users. Here is an example of a guider in Gmail. Google's CSS calls this a promo, likely short for promotional box. <br/><br/> <img src=\"promo_gmail.png\" style=\"border: 1px solid #333;\" />",
-      id: "fifth",
-      next: "finally",
+      id: "guider5",
+      next: "guider6",
       overlay: true,
       title: "How else can I use guiders?",
       width: 550
@@ -144,7 +161,7 @@
     guiders.createGuider({
       buttons: [{name: "Close", classString: "primary-button"}],
       description: "To get started, have a look at this HTML file, then emulate it for use in your own project. Enjoy!",
-      id: "finally",
+      id: "guider6",
       overlay: true,
       title: "Great, so how do I get started?",
       width: 500

diff --git a/README.md b/README.md
@@ -13,8 +13,8 @@ Here are a couple examples hosted online.  You can also check out `README.html`
 [https://optimizely.appspot.com/edit#url=www.google.com](https://optimizely.appspot.com/edit#url=www.google.com)
 
 
-Setup
------
+Set Up
+------
 
 Here is sample code for initializing a couple of guiders.  Guiders are hidden when created, unless `.show()` is method chained immediately after `.createGuider`.
 
@@ -51,7 +51,7 @@ buttons: array of button objects
     name: "Close",
     classString: "primary-button",
     onclick: callback function for when the button is clicked
-      (if name is "close", "next", or "prev", onclick defaults to guiders.hideAll, guiders.next, or guiders.prev respectively)
+      (if name is "close", "next", or "back", onclick defaults to guiders.hideAll, guiders.next, or guiders.prev respectively)
    }
 buttonCustomHTML: (optional) custom HTML that gets appended to the buttons div
 classString: (optional) custom class name that the guider should additionally have
@@ -79,16 +79,38 @@ Besides creating guiders, here is sample code you can use in your application to
 
 ~~~ javascript
 guiders.hideAll(); // hides all guiders
-guiders.next(); // hides the last shown guider, if shown, and advances to the next guider
-guiders.show(id); // shows the guider, given the id used at creation
-guiders.prev(); // shows the previous guider
+guiders.next();    // hides the last shown guider, if shown, and advances to the next guider
+guiders.show(id);  // shows the guider, given the id used at creation
+guiders.prev();    // shows the previous guider
 ~~~
 
 You'll likely want to change the default values, such as the width (set to 400px).  These can be found at the top of `guiders.js` in the `_defaultSettings` object.  You'll also want to modify the css file to match your application's branding.
 
 Creating a multi-page tour?  If the URL of the current window is of the form `http://www.myurl.com/mypage.html#guider=foo`, then the guider with id equal to `foo` will be shown automatically.  To use this, you can set the onHide of the last guider to an anonymous function: function() { window.location.href=`http://www.myurl.com/mypage.html#guider=foo`; }
 
 
+Contributing
+------------
+Contributions are welcome! If you would like to contribute, please issue a pull request against the dev branch, not the master branch.
+
+
+Versioning
+----------
+As of version 2.0.0, Guiders.js will follow the Semantic Versioning guidelines as much as possible.
+
+Releases will follow the following format:
+
+`<major>.<minor>.<patch>`
+
+Updates will occur according to the following guidelines:
+
+* Breaking backward compatibility bumps the major (and resets the minor and patch)
+* New additions without breaking backward compatibility bumps the minor (and resets the patch)
+* Bug fixes and misc changes bumps the patch
+
+For more information on SemVer, visit [http://semver.org/](http://semver.org/).
+
+
 In Closing
 ----------
 

diff --git a/changelog.txt b/changelog.txt
@@ -0,0 +1,26 @@
+CHANGELOG
+
+2.0.0
+-----
+
+- Started keeping a changelog in changelog.txt. (You're reading it!)
+
+- Since this is a major change, I am incrementing the version number to 2.0.0. (Following Semantic Versioning, http://semver.org/)
+
+- Created a dev branch on GitHub. (https://github.com/jeff-optimizely/Guiders-JS/tree/dev) Contributors, issue pull requests to the dev branch so I can safely pull them without worrying about screwing up master code.
+
+- Changed the file names from guiders-(version).js and guiders-(version).css to simply guiders.js and guiders.css, so that it's easier to track changes in GitHub. If you want to know what version you have, just open the file or check guiders.version.
+
+- Upgraded jQuery from 1.51 to 1.90. It should still work with older versions of jQuery.
+
+- Use var guiders = this.guiders = {}; instead of var guiders = (function() { ... }) in order for guiders to attach to the window object more reliably. (Thanks @spmason https://github.com/spmason/Guiders-JS/commit/7229f66870701b980e98d80d1ac79cbb0016b92d#commitcomment-2506855)
+
+- Added bower support in component.json (Thanks rajkissu https://github.com/jeff-optimizely/Guiders-JS/pull/78)
+
+- Added a method: guiders.getCurrentGuider, to get the current guider. This can be useful for analytics tracking, for example.
+
+- guiders.next and guiders.prev return the value of guiders.getCurrent()
+
+- Allow creating guiders in the HTML, then creating guiders via $("#guider2").guider(options).  The options can be passed in through options or set as data-attrs on the object in the HTML. (Thanks @tarr11 https://github.com/jeff-optimizely/Guiders-JS/issues/85)
+
+- jQuery Mask support! If you include the jQuery Mask library in your site, Guiders.js will use jQuery Mask instead of the default overlay.
diff --git a/component.json b/component.json
@@ -0,0 +1,22 @@
+{
+    "name"         : "Guiders-JS",
+    "version"      : "2.0.0",
+    "description"  : "Guiders.js",
+    "main"         : [ "./guiders.js", "./guiders.css", "./guiders_arrows.png", "./guiders_x_button.jpg" ],
+    "homepage"     : "https://github.com/jeff-optimizely/Guiders-JS",
+    "dependencies" : {
+        "jquery" : ">= 1.5.x"
+    },
+    "keywords"     : [
+        "jquery",
+        "guiders",
+        "guider",
+        "guided",
+        "tour"
+    ],
+    "author" : {
+        "name" : "Jeff Pickhardt",
+        "web"  : "http://jeffpickhardt.com"
+    },
+    "license": "http://www.apache.org/licenses/LICENSE-2.0.html"
+}
diff --git a/guiders-1.3.0.css → guiders.css b/guiders-1.3.0.css → guiders.css
diff --git a/guiders.jquery.json b/guiders.jquery.json
@@ -0,0 +1,33 @@
+{
+    "name": "guiders",
+    "title": "Guiders.js",
+    "description": "Guiders.js for adding guided tours to websites.",
+    "keywords": [
+        "guiders",
+        "tours"
+    ],
+    "version": "2.0.0",
+    "author": {
+        "name": "Jeff Pickhardt",
+        "url": "https://github.com/pickhardt"
+    },
+    "maintainers": [
+        {
+            "name": "Jeff Pickhardt",
+            "url": "https://github.com/pickhardt"
+        }
+    ],
+    "licenses": [
+        {
+            "type": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        }
+    ],
+    "bugs": "https://github.com/jeff-optimizely/Guiders-JS/issues",
+    "homepage": "https://github.com/jeff-optimizely/Guiders-JS",
+    "docs": "https://github.com/jeff-optimizely/Guiders-JS",
+    "download": "https://github.com/jeff-optimizely/Guiders-JS",
+    "dependencies": {
+        "jquery": ">=1.3"
+    }
+}