familiarity 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2dd519d51c98acb014642d12b06e4de9a6f82a1b
+  data.tar.gz: 0584a4efa27e079b51ab5e2e1dddd7b7187f872f
+SHA512:
+  metadata.gz: 404901d952f72cb7af44f93413df82792c1c00226e3560bf4553514994f14c1f02f5f8d0d4006f6f14d7fe8b12c2a3c4ad1944a63983f1e4a1835d08630c99f3
+  data.tar.gz: 55ac357617105be747e9e0f4e708bfdc4bf24136b89360ff0d4ed8ab260aee3e43c82a96fe1364deba99415c9cd723d079e7bd597cbc3ef52fb9a03ec1c42b7f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,67 @@
+= \Familiarity
+
+This gem packages a rails engine which provides an interactive demo of features/entities on any given page.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'familiarity', :git => 'git@github.com:praveenkumarsinha/familiarity.git'
+
+Then execute:
+
+    $ bundle
+
+Mount Familiarity at specific location (from routes.rb of application):
+
+      mount Familiarity::Engine, at: "/some_specific_location"
+
+Add javascript(s) in application manifest (most probably from app/assets/javascripts/application.js):
+
+      //= require familiarity/application
+
+Add stylesheet(s) in application manifest (most probably from app/assets/stylesheets/application.css):
+
+       *= require familiarity/application
+
+Add familiarity's switch-board on all the pages (append following helper at the end as body content in layout):
+
+      <%= familiaritySwitchBoard %>
+
+Add familiarity's view on all the pages (append following helper at the end as body content in layout):
+
+      <%= familiarityView %>
+
+== Helpers
+
+To provide a switch board where an user (or may be a bunch of users in any specific environment of application) want to add/edit/update or delete annotations on any page .
+
+    <%= familiaritySwitchBoard %>
+
+
+To provide annotations view of elements, one element at a time on the first visit of page.
+
+    <%= familiarityView %>
+    <%= familiarityView({
+            escape_to_exit: true,           #Exits on ESC key press.
+            f1_to_start: true,              #Starts on F1 key press.
+            show_tips_recursively: false,   #To restart annotations display after complete traverse of available annotations.
+            mandatory_all_tips: true,       #To show all tips(annotations) at least once (before enabling ESC key for exit).
+            traverse_back: true,            #By default 'LEFT' arrow key is available to visit back but which can be disabled  with a 'false' here.
+            remember_duration: 30           #Duration(in days) in which application need to show familiarity view irrespective whether user has viewed them or not.
+        }) %>
+
+
+== Dependencies used
+
+1. https://github.com/carhartl/jquery-cookie
+2. http://iamceege.github.io/tooltipster/
+
+
+== Contributing
+
+1. Fork it ( https://github.com/praveenkumarsinha/familiarity/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 a new Pull Request

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Familiarity'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/familiarity/application.js

@@ -0,0 +1,16 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require ../familiarity/jquery.cookie
+//= require ../familiarity/jquery.tooltipster
+//= require_tree .
+

data/app/assets/javascripts/familiarity/familiarity.js.erb

@@ -0,0 +1,193 @@
+var Familiarity = function (options) {
+    this.escape_to_exit = options.escape_to_exit;
+    this.f1_to_start = options.f1_to_start;
+    this.show_tips_recursively = options.show_tips_recursively;
+    this.mandatory_all_tips = options.mandatory_all_tips;
+    this.traverse_back = options.traverse_back;
+
+    this.familiaritiesUrl = '<%= Familiarity::Engine.routes.url_helpers.familiarities_path(format: :json) %>';
+    // To retain the flag even after reset() method familiarityAllTipsVisited flag is defined here.
+    this.familiarityAllTipsVisited = false;
+    this.reset();
+    Familiarity.setCurrentObject(this);
+}
+Familiarity.setCurrentObject = function (current_object) {
+    return (this.currentObject = current_object);
+}
+Familiarity.getCurrentObject = function () {
+    return this.currentObject
+}
+Familiarity.prototype = {
+    reset: function () {
+//        this.familiarityAllTipsVisited = false;
+        this.familiarityRenderedFlag = false;
+        this.familiarity_hash_pointer = -1;
+        this.familiarity_hash = {};
+        this.familiarity_bubbles = [];
+    },
+    familiarity_hash_keys: function () {
+        return ($.map(this.familiarity_hash, function (v, k) {
+            return k;
+        }));
+    },
+    showNextBubble: function () {
+        if (this.familiarity_hash_keys().length <= 0) {
+            return false;
+        }
+        this.familiarity_hash_pointer++;
+        if ((this.familiarity_hash_pointer + 1) > this.familiarity_hash_keys().length) {
+            this.familiarityAllTipsVisited = true
+            if (this.show_tips_recursively) {
+                this.familiarity_hash_pointer = 0;
+            } else {
+                this.familiarityView(false);
+                return true;
+            }
+        }
+        this.showOneByOne();
+    },
+    showPreviousBubble: function () {
+        if (this.familiarity_hash_keys().length <= 0) {
+            return false;
+        }
+        if (!this.traverse_back) {
+            return false;
+        }
+        this.familiarity_hash_pointer--;
+        if (this.familiarity_hash_pointer < 0) {
+            if (this.show_tips_recursively) {
+                this.familiarity_hash_pointer = this.familiarity_hash_keys().length - 1;
+            } else {
+                this.familiarity_hash_pointer = 0;
+            }
+        }
+        this.showOneByOne();
+    },
+    showOneByOne: function () {
+//        console.log(this.familiarity_hash_pointer);
+//        console.log(this.familiarity_hash);
+//        console.log(this.familiarity_bubbles);
+        this.hideFBubbles();
+        return this.showFBubble();
+    },
+    showFBubble: function () {
+        var current_bubble_key = this.familiarity_hash_keys()[this.familiarity_hash_pointer];
+        var element = $(current_bubble_key)
+        var content = this.familiarity_hash[current_bubble_key];
+
+        if (element.length <= 0) {
+            return false;
+        }
+
+        element.addClass('familiarity-bubble-parent')
+                .tooltipster({
+                    content: $('<span><strong>' + content.replace(/\n/g, "<br/>") + '</strong></span>'),
+                    maxWidth: 400,
+                    animation: 'grow', //fade, grow, swing, slide, fall
+                    autoClose: true, //true, false
+                    position: 'bottom-right', //right, left, top, top-right, top-left, bottom, bottom-right, bottom-left
+                    delay: 700,
+                    speed: 700,
+                    theme: 'tooltipster-default',
+                    touchDevices: false,
+                    trigger: 'custom' //hover, click, custom
+                });
+        element.tooltipster('show');
+//        console.log(element.css('background-color'));
+//        if (element.css('background-color') == 'transparent') {
+//            element.css('background-color', 'white')
+//        }
+        this.familiarity_bubbles.push(element)
+        return true;
+    },
+    hideFBubbles: function () {
+        while (this.familiarity_bubbles.length > 0) {
+            this.familiarity_bubbles.pop().tooltipster('destroy').removeClass('familiarity-bubble-parent').attr('title', null);
+        }
+    },
+    fetchFamiliarities: function (callback) {
+        if (typeof(callback) != 'function') {
+            callback = function (familiarity_hash) {
+                console.log('familiarity_hash');
+                console.log(familiarity_hash);
+            }
+        }
+        var _this = this;
+        $.get(this.familiaritiesUrl, function (data) {
+            var familiarity_hash = data[$(location).attr('pathname')]
+            if (familiarity_hash == null) {
+                familiarity_hash = {}
+            }
+            _this.familiarity_hash = familiarity_hash;
+            callback(familiarity_hash);
+        });
+    },
+    familiarityView: function (enable) {
+        var _this = this;
+        if (typeof(enable) == 'undefined') {
+            enable = true;
+        }
+        if (enable == true) {
+            //Re-setting all values and variables (in case is there any half done state)
+            this.reset();
+
+            //Making bubble pop-out //////////////////
+            this.fetchFamiliarities(function (familiarity_hash) {
+                        if (_this.familiarity_hash_keys().length > 0) {
+                            //Rendering overlay
+                            $('body').addClass('familiarity-view').append($('<div id="familiarity_dim"></div>'));
+
+                            //Rendering first bubble (via Next Bubble)
+                            _this.showNextBubble();
+
+                            //Marking flag that familiarity_view is rendered
+                            _this.familiarityRenderedFlag = true;
+                        }
+                    }
+            );
+
+        } else {
+
+            // If option 'mandatory_all_tips' is true then make sure all tips has been rendered
+            // before exit of familiarity view
+            if (this.mandatory_all_tips && (!this.familiarityAllTipsVisited)) {
+                return false;
+            }
+
+            //Removing bubbles
+            _this.hideFBubbles();
+
+            //Removing rendered overlay
+            $('#familiarity_dim').remove();
+            $('body').removeClass('familiarity-view');
+
+            //Marking flag that familiarity_view is removed from viewport
+            this.familiarityRenderedFlag = false;
+        }
+    }
+
+}
+
+$(document).on("page:change", function () {
+// Show and hide on F1 and ESC key respectively
+    $('body').keyup(function (e) {
+        var _this = Familiarity.getCurrentObject();
+        if (typeof(_this) != "undefined" && e.keyCode == 27 && _this.escape_to_exit && _this.familiarityRenderedFlag) { //ESC key pressed
+            _this.familiarityView(false);
+        }
+        if (typeof(_this) != "undefined" && e.keyCode == 112 && _this.f1_to_start && !_this.familiarityRenderedFlag) { //F1 key pressed
+            _this.familiarityView(true);
+        }
+        if (typeof(_this) != "undefined" && e.keyCode == 37 && _this.familiarityRenderedFlag) { //LEFT arrow key pressed
+            _this.showPreviousBubble();
+        }
+        if (typeof(_this) != "undefined" && e.keyCode == 39 && _this.familiarityRenderedFlag) { //RIGHT arrow key pressed
+            _this.showNextBubble()
+        }
+    }).mousedown(function (e) {
+        var _this = Familiarity.getCurrentObject();
+        if (typeof(_this) != "undefined" && _this.familiarityRenderedFlag) { //Show next bubble on mouse down('click')
+            _this.showNextBubble()
+        }
+    });
+});

data/app/assets/javascripts/familiarity/familiarity_admin.js.erb

@@ -0,0 +1,150 @@
+jQuery.fn.getPath = function () {
+    if (this.length != 1) throw 'Requires one element.';
+
+    var path, node = this;
+    while (node.length) {
+        var realNode = node[0], name = realNode.localName;
+        if (!name) break;
+        name = name.toLowerCase();
+
+        var parent = node.parent();
+
+        var siblings = parent.children(name);
+        if (siblings.length > 1) {
+            name += ':eq(' + siblings.index(realNode) + ')';
+        }
+
+        path = name + (path ? '>' + path : '');
+        node = parent;
+    }
+
+    return path;
+};
+
+var FamiliarityAdmin = function () {
+    this.familiarityEditorialSet = {};
+    this.familiaritySaveUrl = '<%=Familiarity::Engine.routes.url_helpers.save_familiarities_path(format: :json)%>';
+    this.familiaritiesUrl = '<%= Familiarity::Engine.routes.url_helpers.familiarities_path(format: :json) %>';
+}
+
+FamiliarityAdmin.familiaritySwitchBoard = function () {
+    var familiarity_admin = new FamiliarityAdmin();
+
+    var switch_state = 'On';
+    $('div.familiaritySwitch').remove();
+    var _div = $('<div class="familiaritySwitch"></div>').html('<div class="text_content">Switch ' + switch_state + ' familiarity!</div>').click(function () {
+        familiarity_admin.familiaritySwitch(switch_state);
+        switch_state = (switch_state == "On") ? "Off" : "On";
+        $(this).html('<div class="text_content">Switch ' + switch_state + ' familiarity!</div>');
+    }).appendTo($('body'));
+}
+
+FamiliarityAdmin.prototype = {
+    findOrBuildPopup: function (selection_path, inner_text) {
+        if (typeof(inner_text) == 'undefined') {
+            inner_text = "";
+        }
+        var _div = this.familiarityEditorialSet[selection_path];
+        if (_div == null) {
+            var _div = $('<div class="familiarityPopUpEdit" style="z-index: 20;position: absolute;left: 0;top: 0;display: none"><textarea class="textarea_class" placeholder="Short sweet tutorial goes in here."></textarea><br/><a class="a_class">Close</a></div>');
+
+            //Adding 'Close' handler
+            _div.children('a').click(function () {
+                $(this).parents('div.familiarityPopUpEdit').hide();
+            });
+
+            //Populating textarea
+            _div.children('textarea').val(inner_text);
+
+            this.familiarityEditorialSet[selection_path] = _div;
+
+            _div.appendTo($('body'));
+        }
+        $.each(this.familiarityEditorialSet, function (k, v) {
+            v.hide();
+        });
+        return _div;
+    },
+    startFamiliarizing: function () {
+        var _current_object = this;
+        $('.familiarityTag').bind("mouseenter.myFamiliarity", function (e) {
+            var _this = $(this);
+            var currentSelectionPath = _this.getPath();
+//            console.log(currentSelectionPath);
+            _this.addClass('familiar-selector');
+            _this.parents().removeClass('familiar-selector');
+
+            e.stopImmediatePropagation();
+        }).bind("mouseleave.myFamiliarity", function (e) {
+            var _this = $(this);
+            var currentSelectionPath = _this.getPath();
+            _this.removeClass('familiar-selector');
+
+            e.stopImmediatePropagation();
+        }).bind("click.myFamiliarity", function (e) {
+            var _this = $(this);
+            var currentSelectionPath = _this.getPath();
+
+            var _left_position = _this.position().left;
+            var _top_position = _this.position().top + _this.height();
+
+            var _div = _current_object.findOrBuildPopup(currentSelectionPath).css({
+                left: _left_position,
+                top: _top_position
+            }).show().children('textarea').focus();
+
+//                    console.log(_this);
+            e.preventDefault();
+            e.stopPropagation();
+        });
+    },
+
+    saveToBackEnd: function () {
+        var _result_hash = {}
+        $.each(this.familiarityEditorialSet, function (k, v) {
+            if (v.children('textarea').val().trim().length > 0) {
+                _result_hash[k] = v.children('textarea').val();
+            }
+        })
+        jQuery.post(this.familiaritySaveUrl, {
+            from_page: $(location).attr('pathname'),
+            'familiarity_hash': _result_hash
+        });
+    },
+
+    stopFamiliarizing: function () {
+        $('.familiarityTag').unbind('.myFamiliarity');
+    },
+
+    familiaritySwitch: function (i_switch) {
+        if (i_switch == "Off") {
+            this.stopFamiliarizing();
+            $('.familiarityPopUpEdit').hide();
+            if (confirm("Do you want to save the collected familiarity data?")) {
+                this.saveToBackEnd();
+            }
+        }
+        $.each($('body *:not(.familiaritySwitch, .familiarityPopUpEdit)'), function (i, e) {
+            if (i_switch == "On") {
+                if ($(e).parents('.familiarityPopUpEdit').length <= 0) {
+                    $(e).addClass('familiarityTag');
+                }
+            } else {
+                $(e).removeClass('familiarityTag');
+            }
+        });
+        if (i_switch == "On") {
+            var _current_object = this;
+            this.startFamiliarizing();
+            $.get(this.familiaritiesUrl, function (data) {
+                var familiarity_hash = data[$(location).attr('pathname')]
+                if (familiarity_hash == null) {
+                    familiarity_hash = {}
+                }
+                $.each(familiarity_hash, function (k, v) {
+                    _current_object.findOrBuildPopup(k, v);
+                });
+            });
+        }
+    }
+}

data/app/assets/javascripts/familiarity/jquery.cookie.js

@@ -0,0 +1,117 @@
+/*!
+ * jQuery Cookie Plugin v1.4.1
+ * https://github.com/carhartl/jquery-cookie
+ *
+ * Copyright 2013 Klaus Hartl
+ * Released under the MIT license
+ */
+(function (factory) {
+	if (typeof define === 'function' && define.amd) {
+		// AMD
+		define(['jquery'], factory);
+	} else if (typeof exports === 'object') {
+		// CommonJS
+		factory(require('jquery'));
+	} else {
+		// Browser globals
+		factory(jQuery);
+	}
+}(function ($) {
+
+	var pluses = /\+/g;
+
+	function encode(s) {
+		return config.raw ? s : encodeURIComponent(s);
+	}
+
+	function decode(s) {
+		return config.raw ? s : decodeURIComponent(s);
+	}
+
+	function stringifyCookieValue(value) {
+		return encode(config.json ? JSON.stringify(value) : String(value));
+	}
+
+	function parseCookieValue(s) {
+		if (s.indexOf('"') === 0) {
+			// This is a quoted cookie as according to RFC2068, unescape...
+			s = s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+		}
+
+		try {
+			// Replace server-side written pluses with spaces.
+			// If we can't decode the cookie, ignore it, it's unusable.
+			// If we can't parse the cookie, ignore it, it's unusable.
+			s = decodeURIComponent(s.replace(pluses, ' '));
+			return config.json ? JSON.parse(s) : s;
+		} catch(e) {}
+	}
+
+	function read(s, converter) {
+		var value = config.raw ? s : parseCookieValue(s);
+		return $.isFunction(converter) ? converter(value) : value;
+	}
+
+	var config = $.cookie = function (key, value, options) {
+
+		// Write
+
+		if (value !== undefined && !$.isFunction(value)) {
+			options = $.extend({}, config.defaults, options);
+
+			if (typeof options.expires === 'number') {
+				var days = options.expires, t = options.expires = new Date();
+				t.setTime(+t + days * 864e+5);
+			}
+
+			return (document.cookie = [
+				encode(key), '=', stringifyCookieValue(value),
+				options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
+				options.path    ? '; path=' + options.path : '',
+				options.domain  ? '; domain=' + options.domain : '',
+				options.secure  ? '; secure' : ''
+			].join(''));
+		}
+
+		// Read
+
+		var result = key ? undefined : {};
+
+		// To prevent the for loop in the first place assign an empty array
+		// in case there are no cookies at all. Also prevents odd result when
+		// calling $.cookie().
+		var cookies = document.cookie ? document.cookie.split('; ') : [];
+
+		for (var i = 0, l = cookies.length; i < l; i++) {
+			var parts = cookies[i].split('=');
+			var name = decode(parts.shift());
+			var cookie = parts.join('=');
+
+			if (key && key === name) {
+				// If second argument (value) is a function it's a converter...
+				result = read(cookie, value);
+				break;
+			}
+
+			// Prevent storing a cookie that we couldn't decode.
+			if (!key && (cookie = read(cookie)) !== undefined) {
+				result[name] = cookie;
+			}
+		}
+
+		return result;
+	};
+
+	config.defaults = {};
+
+	$.removeCookie = function (key, options) {
+		if ($.cookie(key) === undefined) {
+			return false;
+		}
+
+		// Must not alter options, thus extending a fresh object...
+		$.cookie(key, '', $.extend({}, options, { expires: -1 }));
+		return !$.cookie(key);
+	};
+
+}));