tips 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9684df1fded8d68ca41ee1ce6f427df5af471b34
-  data.tar.gz: dfbf087e71d2d7d8d9553bf560e00e1254b45081
+  metadata.gz: 88eefb61e9358a7277d98c91dab830c502ac3032
+  data.tar.gz: 921e3580b09209f64afd35b78beb38ba3f55488d
 SHA512:
-  metadata.gz: 405cd0a5dcb1b15ee664b066a23149bb893dc4aff4d18c3b6e5635c20c2911a3339b6d7fe1a588a520af4f19443dfcb293a1d501e32c0fcdb013bd176e8204d3
-  data.tar.gz: a1f9c2b17f0230b56b385db8d3a756689eb4cc819688405fd86d51f4efbdd63143ac1ee771ee5f6ad9b90274b1e4ba6d4a55c3adc5b875b47a3fed0dddcf052d
+  metadata.gz: f8ffee509e78bd2b222e7eaee4faf725feab0936743474ff94361b62c118374b6925f26eb26c9dc2e7b637c26c72cad1f70f25e3cfd3a37350de116dc652a48c
+  data.tar.gz: 8f4a860f9dcb5120c707ba75481896c590c83bb96207968ad933d42e72f91cb5fdd9d8f6a5a800537ddb6e2f65095b2774f82b8835c9b9207ca1bfb035172f8f

data/README.markdown

@@ -0,0 +1,307 @@
+# Tips (beta)
+
+Slack inspired onboarding tips.
+
+Note: Tips is currently in Beta. Left, much work there is. To see a backlog of features and work currently in progress <a href='https://huboard.com/rguerrettaz/tips-rails/' target='_blank'>checkout the HuBoard.</a>
+
+<a href="http://codepen.io/rguerrettaz/pen/eNNXKB" target='_blank'><img src="http://i.imgur.com/EQuPxuh.gif"></a>
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'tips'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tips
+
+## Examples
+
+* <a href="http://codepen.io/rguerrettaz/pen/LVVVzR" target='_blank'>Single Tip</a>
+* <a href="http://codepen.io/rguerrettaz/pen/doorJm" target='_blank'>Single Tip, multiple pages of content</a>
+* <a href="http://codepen.io/rguerrettaz/pen/KppEop" target='_blank'>Multiple Tips</a>
+* <a href="http://codepen.io/rguerrettaz/pen/eNNXKB" target='_blank'>Multiple Tips, multiple pages of content</a>
+
+## Usage
+
+Tips uses HTML data-attributes to pass the majority of its configuration.
+
+#### Creating a tip
+
+Creating a tip is easy. Just add the necessary data-attributes to your target
+element and call `Tips.init()`. For example, if you want to target a div on your
+page you'd add the following data-attributes to the div:
+
+```html
+<div  data-tips-id='my-unique-tip-name'
+      data-tips-content='{"page1Header" : "This is my header",
+                          "page1Body"   : "This is the body of my tip",
+                        }'
+      data-tips-hot-spot-position='top-right'
+      data-tips-card-position='right'
+      data-tips-priority='1'
+      data-tips-pages='1'>
+</div>
+```
+
+Once the data attributes have been added add this line to your javascript
+```javascript
+Tips.init()
+```
+
+#### Creating multiple tips on a single page
+
+Use the same data-attributes as a single tip just make sure `data-tips-id` is
+unique for each tip and set the `data-tips-priority` appropriately.
+
+```html
+<div  data-tips-id='my-unique-tip-name'
+      data-tips-content='{"page1Header" : "This is my header",
+                          "page1Body"   : "This is the body of my tip",
+                        }'
+      data-tips-hot-spot-position='top-right'
+      data-tips-card-position='right'
+      data-tips-priority='1'
+      data-tips-pages='1'>
+  <button>My 1st Button</button>
+</div>
+
+<div  data-tips-id='my-unique-tip-name-number-two'
+      data-tips-content='{"page1Header" : "This is my header no. 2",
+                          "page1Body"   : "This is the body of my tip no. 2",
+                        }'
+      data-tips-hot-spot-position='top-right'
+      data-tips-card-position='right'
+      data-tips-priority='2'
+      data-tips-pages='1'>
+  <button>My 2nd Button</button>
+</div>
+
+```
+
+Once the data attributes have been added add this line to your javascript
+```javascript
+Tips.init()
+```
+
+#### Creating tips with multiple pages of content
+
+To do this just add the extra pages to `data-tips-content`
+```html
+<div  data-tips-id='my-unique-tip-name'
+      data-tips-content='{"page1Header" : "This is my header",
+                          "page1Body"   : "This is the body of my tip",
+                          "page2Header" : "A second header?",
+                          "page2Body"   : "Yes! If you so choose, you can have
+                                          tips with multiple pages."
+                        }'
+      data-tips-hot-spot-position='top-right'
+      data-tips-card-position='right'
+      data-tips-priority='1'
+      data-tips-pages='1'>
+  <button>My 1st Button</button>
+</div>
+```
+
+Once the data attributes have been added add this line to your javascript
+```javascript
+Tips.init()
+```
+
+## Attributes overview
+
+#### data-tips-id
+`data-tips-id` should be unique for each tip you have on your website.
+These are used as references when we check if a user has previously seen a tip.
+
+```
+data-tips-id='some-unique-name-for-this-tip'
+```
+
+#### data-tips-content
+`data-tips-content` is a JSON string representation of the content for your tip.
+To allow Tips to support multiple pages of content we use keys in the form of
+`page1Header` and `page1Body`. Pages should be sequential. Shit will fail
+otherwise.
+
+```
+data-tips-content='{"page1Header":"The header for the first page of this tip",
+                    "page1Boy":"The body for the first page of this tip",
+                    "page2Header":"The header for the second page of this tip",
+                    "page2Body":"The body for the second page of this tip"
+                   }
+```
+
+#### data-tips-hot-spot-position
+`data-tips-hot-spot-position` controls the position of the throbbing hot spot
+icon in relation to the element you're targeting.
+
+
+```html
+<!-- Default value: 'right' -->
+data-tips-hot-spot-position='bottom-left'
+```
+
+Acceptable values:
+```
+top-right
+top-left
+top
+bottom-right
+bottom-left
+bottom
+left
+right
+middle
+```
+
+#### data-tips-card-position
+`data-tips-card-position` controls the side your tip modal will show up on.
+
+```
+<!-- Default value: 'right' -->
+data-tips-card-position='left'
+```
+
+Acceptable values:
+```
+top
+bottom
+left
+right
+```
+
+#### data-tips-priority
+`data-tips-priority` is used when you have multiple tips on a given page.
+Priority 1 will be shown first.
+```
+data-tips-priority='1'
+```
+
+#### data-tips-pages
+`data-tips-pages` tells Tips how many pages you want on a given tip. Required
+attribute. There is no default set at this point.
+```
+data-tips-priority='1'
+```
+
+## Storage
+#### Default Storage (localStorage)
+By default Tips will use `localStorage` to store which tips have been seen.
+This works, however, it's sub-optimal. Using `localStorage` means tips may be
+seen twice. When using localStorage the following scenarios may show tips twice:
+* User opens pages in incognito mode
+* User opens pages in multiple browsers
+* User opens pages from multiple devices
+
+Because the lack of persistence with `localStorage`, Tips comes with the ability
+to [define your own](#custom-storage-device) `customStorageDevice`.
+
+Here's the `defaultStorageDevice`:
+```javascript
+var defaultStorageDevice = {
+      optOutKey: 'tips-opted-out',
+
+      addTip: function(tipName){
+        localStorage.setItem(tipName, true);
+      },
+
+      tipHasBeenSeen: function(tipName){
+        return !!localStorage.getItem(tipName);
+      },
+
+      optOut: function(){
+        localStorage.setItem(this.optOutKey, true);
+      },
+
+      userHasOptedOut: function(){
+        return !!localStorage.getItem(this.optOutKey);
+      },
+
+      removeAll: function(tipNames){
+        tipNames.push(this.optOutKey);
+        tipNames.forEach(function(key){
+          localStorage.removeItem(key);
+        });
+      }
+    };
+```
+
+#### Custom Storage Device
+You can define your own custom storage device and pass it in as an argument when
+you initialize with `Tips.init(myCustomStorageDevice)`. Example using `jQuery`:
+```javascript
+(function initTipsWithCustomStorage() {
+
+  // Make an ajax call for a list of seen tips and if the user has opted out
+  // On success, init tips with out customStorageDevice
+  (function(){
+    $.ajax('/tips/data', {
+      method: 'GET'
+    })
+    .success(function(data){
+      var userHasOptedOut = data.optedOut;
+      var seenTips        = data.seenTips;
+      var storageDevice   = {
+        seenTips: seenTips,
+
+        addTip: function(tipName){
+          $.ajax('/tips/tip_seen', {
+            method: 'POST',
+            data: {name: tipName}
+          });
+
+          // Add tip to list of seenTips so it doesn't show again in the same
+          // window session
+          seenTips.push(tipName);
+        },
+
+        tipHasBeenSeen: function(tipName){
+          return seenTips.indexOf(tipName) != -1;
+        },
+
+        optOut: function(){
+          $.ajax('/tips/opted_out', {
+            method: 'POST',
+            data: {name: 'opt-out'}
+          })
+        },
+
+        userHasOptedOut: function(){
+          return !!userHasOptedOut;
+        },
+      };
+
+      // Begin the magic
+      Tips.init(storageDevice);
+    })
+    .fail(function(jqXHR, textStatus){
+      console.log('Failure? Yes, failure with status: ' + textStatus)
+    });
+  })();
+})();
+
+```
+
+Important things to note here
+* You're passing an object with public methods, not a function
+* You must have the following methods defined
+```javascript
+storageDevice.addTip()
+storageDevice.tipHasBeenSeen()
+storageDevice.optOut()
+storageDevice.userHasOptedOut()
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/tips/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/app/assets/javascripts/tips.js

@@ -1,6 +1,13 @@
 ;(function setup(window){
 
   function initTips(){
+
+    //
+    //
+    // Validation
+    // TODO: add validation to tip data-attributes config
+    //
+    //
     function Validation(config, settableAttrs, acceptableValues) {
 
       function logInvalidKeyError(key){
@@ -25,42 +32,19 @@
       })
     }
 
-    //
-    //
-    // STORAGE DEVICE
-    //
-    //
-    var tipsCustomStorageDevice;
-    var storageDevice;
-    var defaultStorageDevice = {
-      optOutKey: 'tips-opted-out',
-
-      addTip: function(tipName){
-        localStorage.setItem(tipName, true);
-      },
-
-      tipHasBeenSeen: function(tipName){
-        return !!localStorage.getItem(tipName);
-      },
-
-      optOut: function(){
-        localStorage.setItem(this.optOutKey, true);
-      },
-
-      userHasOptedOut: function(){
-        return !!localStorage.getItem(this.optOutKey);
-      },
+    function createTips(){
+      var tipNodes = document.querySelectorAll('[data-tips-id]');
 
-      removeAll: function(tipNames){
-        tipNames.push(this.optOutKey)
-        tipNames.forEach(function(key){
-          localStorage.removeItem(key)
-        })
+      for(i = 0; i < tipNodes.length; ++i) {
+        var tip = new Tip(tipNodes[i])
+        Tips.list.push(tip)
       }
     };
 
-    if (tipsCustomStorageDevice == undefined) storageDevice = defaultStorageDevice;
-    else storageDevice = tipsCustomStorageDevice();
+    // Sort list to make TipCard showing easier
+    function sortTipsList(list){
+      Tips.list.sort(function(a,b) {return a.priority - b.priority})
+    }
 
     //
     //
@@ -68,11 +52,52 @@
     //
     //
     var Tips = {
+      init: function(customStorageDevice){
+
+        // Allow user to define their own storageDevice
+        if(customStorageDevice != undefined) {
+          this.storageDevice = customStorageDevice;
+        }
+
+        createTips();
+        sortTipsList();
+        this.showNextTip();
+      },
+
       list: [],
 
-      userOptedOut: function(){ return storageDevice.userHasOptedOut() },
+      storageDevice: {
+        optOutKey: 'tips-opted-out',
+
+        addTip: function(tipName){
+          localStorage.setItem(tipName, true);
+        },
+
+        tipHasBeenSeen: function(tipName){
+          console.log(" I GET CALLED BEFORE I GET OVERWRITTEN")
+          console.log(tipName)
+          return !!localStorage.getItem(tipName);
+        },
+
+        optOut: function(){
+          localStorage.setItem(this.optOutKey, true);
+        },
 
-      reset: function(){ storageDevice.removeAll(this.tipNames()) },
+        userHasOptedOut: function(){
+          return !!localStorage.getItem(this.optOutKey);
+        },
+
+        removeAll: function(tipNames){
+          tipNames.push(this.optOutKey)
+          tipNames.forEach(function(key){
+            localStorage.removeItem(key)
+          })
+        }
+      },
+
+      userOptedOut: function(){ return this.storageDevice.userHasOptedOut() },
+
+      reset: function(){ this.storageDevice.removeAll(this.tipNames()) },
 
       tipNames: function(){
         var names = [];
@@ -102,7 +127,7 @@
     //
     //
     function Tip(el) {
-      this.name = 'tips:' + el.getAttribute('data-tips-name');
+      this.name = 'tips:' + el.getAttribute('data-tips-id');
       this.priority = el.getAttribute('data-tips-priority') || 1;
       this.pages = el.getAttribute('data-tips-pages') || 1;
       this.tipNode = el;
@@ -116,7 +141,7 @@
 
     Tip.prototype.hasBeenSeen = function() {
       //Look in storage device for tip seen
-      return !!storageDevice.tipHasBeenSeen(this.name)
+      return !!Tips.storageDevice.tipHasBeenSeen(this.name)
     }
 
     //
@@ -217,7 +242,7 @@
       }
 
       function storeThatTipHasBeenSeen(){
-        storageDevice.addTip(hotSpot.tipName);
+        Tips.storageDevice.addTip(hotSpot.tipName);
       }
 
       function showTipCard(){
@@ -248,7 +273,8 @@
         // Highlight the tip node
         // For z-index to work the tipNode must have a positon in the following:
         // ['absolute', 'relative', 'fixed']
-        this.tipNode.style.zIndex = 9999;
+        // TODO: only hightlight the element if user sets it in config
+        // this.tipNode.style.zIndex = 9999;
       };
 
       tipCard.hide = function(){
@@ -459,7 +485,7 @@
       function addOptOutListener(optOutLink) {
         optOutLink.addEventListener('click', function(e){
           e.preventDefault();
-          storageDevice.optOut();
+          Tips.storageDevice.optOut();
           tipCard.hide();
         })
       };
@@ -553,24 +579,6 @@
       return this.charAt(0).toUpperCase() + this.slice(1);
     }
 
-    function createTips(){
-      var tipNodes = document.querySelectorAll('[data-tips-single-item]');
-
-      for(i = 0; i < tipNodes.length; ++i) {
-        var tip = new Tip(tipNodes[i])
-        Tips.list.push(tip)
-      }
-    };
-
-    // Sort list to make TipCard showing easier
-    function sortTipsList(list){
-      Tips.list.sort(function(a,b) {return a.priority - b.priority})
-    }
-
-    createTips();
-    sortTipsList();
-    Tips.showNextTip();
-
     return Tips;
   }
 

data/lib/tips/version.rb

@@ -1,3 +1,3 @@
 module Tips
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: tips
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Ryan Guerrettaz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-24 00:00:00.000000000 Z
+date: 2015-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: ''
@@ -45,10 +45,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
-- README.md
+- README.markdown
 - Rakefile
 - app/assets/images/tip_throbber.png
 - app/assets/javascripts/tips.js
@@ -67,17 +67,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.1
+rubygems_version: 2.2.3
 signing_key: 
 specification_version: 4
 summary: Slack inspired onboarding tips

data/README.md

@@ -1,29 +0,0 @@
-# Tips
-
-TODO: Write a gem description
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'tips'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install tips
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Contributing
-
-1. Fork it ( http://github.com/<my-github-username>/tips/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request