ui_guiders 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.1.3"
+  gem "jeweler", "~> 1.8.3"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.1.3)
+  jeweler (~> 1.8.3)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Roman Snitko
+
+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.markdown

@@ -0,0 +1,96 @@
+UIGuiders
+=========
+
+*Visual guiders for website UIs*
+It's like "Guiders-JS", but easily customizable and less js-centric.
+
+Why?
+----
+Because I wanted an easy soulution that wouldn't be all javascript. I don't think it's a good idea to assign
+guiders on the js-level, like Guiders.js does. Instead, it should be in the views. The javascript part
+only handles proper positioning and effects part, while remaining uninvolved into the styles/content business.
+
+If you wish, you may just use the js part and use it outside of the Rails app.
+(Actually, it's written in coffeescript, so you'd have to compile it first).
+
+The javascript part will correctly determine which part of the screen the target DOM-element is positioned and
+then choose how to display the guider - what side the arrow should be on and should the guider be on top or
+at the bottom of the target DOM-element. No need to manually specify any options.
+
+See Screenshot.png file for a small demonstration of how it looks.
+
+INSTALLATION
+------------
+
+1. gem install ui_guiders
+
+2. 
+  (a) Add to your scss: `@import "ui_guiders";` OR
+  (b) Add to your layout: `stylesheet_link_tag 'ui_guiders'`
+
+3.
+  (a) Add to your application.js.coffee `#= require lib/ui_guiders` OR
+  (b) Add to your layout: `javascript_include_tag "lib/ui_guiders"`
+
+
+Usage
+-----
+
+This is what you put in your views (haml example):
+
+    = ui_guider :target => "header .menuItem1", :autoshow => true, :event => "click", :show_once => true, :id => "menu_item_1_guider", :class => "myclass" do
+        text explaining
+        this awesome menuitem
+
+That's it. Now when your page is loaded a shiny yellow guider will appear pointing at the DOM element you specified with the :target option.
+Other options explanation:
+
+`:autoshow`    if true, js-part of the plugin will force the guider to appear up
+               immediately after the page loads. Default is false.
+
+`:autohide`    if true, it hides the guider whenever the `mouseout` event happens on the target element.
+               The close ico does not appear if this option is enabled (because this option also adds `autohide` class to
+               the .uiGuider element, and default css sets a `display` property of `img.close` in it to `none`).
+
+`:show_once`   Saves cookie with the id of the guider. Next time the user visits, the guider is not shown.
+               Default is false.
+
+`:event`       jQuery event (for example `click` or `mouseover`) which is binded to the target and on which the guider is shown.
+
+`:side_arrow`  Normally the arrow would appear either on top or the bottom side of the guider, but with this option set to true, you can an arrow
+               on either left or right side of the guider. Use with caution, as this may force horizontal scrollbars to appear if your targer is
+               placed to close the edge of the screen.
+
+`:target_edge` Sets a horizontal location on the target for the arrow to point to, possible values are "left", "right" or "middle"
+               (default is "middle").
+
+`:id`
+`:class`       Both are applied to the html-element.
+
+
+Customization
+-------------
+* Want different styles?
+  copy `app/assets/stylesheets/ui_guiders.css.scss` from the gem dir and change it.
+
+* Replacing images?
+  You guessed it right. Copy `app/assets/images/ui_guiders/` from the gem dir and change it.
+
+For images and stylesheets make sure your `app/assets` dir loads last, so that Rails loads *your* files.
+I managed to do it with
+
+    config.assets.paths << "#{Rails.root}/app/assets/stylesheets/" 
+    config.assets.paths << "#{Rails.root}/app/assets/images/"
+
+in my `config/application.rb`
+
+* Want a different markup?
+  copy `app/assets/views/shared/_ui_guider.haml` from the plugin dir and change it.
+
+
+Requirements
+------------
+
+  * Rails 3.1 (sorry, no 3.0 support, using assets)
+  * jQuery (tested on 1.5.2)
+  * jquery.cookie.js 

data/Rakefile

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "ui_guiders"
+  gem.homepage = "http://github.com/snitko/ui_guiders"
+  gem.license = "MIT"
+  gem.summary = "Visual guiders for website UIs."
+  gem.description = "It's like \"Guiders-JS\", but easily customizable and less js-centric."
+  gem.email = "roman.snitko@gmail.com"
+  gem.authors = ["Roman Snitko"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/assets/javascripts/lib/ui_guiders.js.coffee

@@ -0,0 +1,159 @@
+jQuery ($) ->
+
+  window.UIGuider = class UIGuider
+      
+    constructor: (block) ->
+      @block        = $(block)
+      @target       = $($(@block).attr("data-target-element"))
+      @arrows = {
+        top:    @block.children(".arrow.top")
+        bottom: @block.children(".arrow.bottom")
+        left:   @block.children(".arrow.side.left")
+        right:  @block.children(".arrow.side.right")
+      }
+      @state = "hidden"
+
+      @hide_arrows = () ->
+        for a in @arrows
+          a.hide()
+
+      # Places arrow to the right corner of the Guider.
+      # It's top/bottom and left/right position is always equal to that
+      # of a target.
+      @place_arrow = (pos, options={}) ->
+        @hide_arrows()
+        if options.side_arrow
+          @arrows[pos.x].css(top: @block.height()/2 - @arrows.left.height()).show()
+        else
+          @arrows[pos.y].show().addClass(pos.x)
+        
+      # Places Guider so that its arrow always points to the target.
+      # Depending on the position of the target the guider will appear on the left
+      # or on the right side of the target.
+      #
+      # To set a horizontal location on the target for the arrow to point to,
+      # use "edge" option for that with "left", "right" or "middle" (default is "middle").
+      #
+      # To set the type of arrow (side arrow or arrows appearing on the top or the bottom of the guider),
+      # set "side_arrow" option to true.
+      @place_guider = (pos, options={}) ->
+
+        if options.side_arrow
+          arrow = @arrows.left
+          arrow_offset_sign = 1
+        else
+          arrow = @arrows.top
+          arrow_offset_sign = -1
+
+        if options.side_arrow
+          top_offset = @target.offset().top + @target.height()/2 - @block.height()/2
+        else if pos.y == "top"
+          top_offset = @target.offset().top + @target.height() + arrow.height()
+        else
+          top_offset = @target.offset().top - @block.height() - arrow.height()
+
+        if pos.x == "left"
+          pos_left_offset = @target.offset().left + arrow.width()*arrow_offset_sign
+          if options.edge == "left"
+            width_left_offset = 0
+          else if options.edge == "right"
+            width_left_offset = @target.width()
+          else
+            width_left_offset = @target.width()/2
+        else
+          arrow_offset_sign = -arrow_offset_sign
+          pos_left_offset = @target.offset().left + arrow.width()*arrow_offset_sign
+          if options.edge == "left"
+            width_left_offset = -@block.width()
+          else if options.edge == "right"
+            width_left_offset = -@block.width() + @target.width()
+          else
+            width_left_offset = -@block.width() + @target.width()/2
+
+
+        @block.css { top: top_offset }
+        @block.css { left: pos_left_offset + width_left_offset }
+
+
+      @set_cookie = () ->
+        $.cookie("UIGuider_#{@block.attr("id")}", "1", { expires: 3560 }) if @block.hasClass("show_once") and @block.attr("id")
+
+      # Finds which part of the screen the target is located,
+      # top/bottom and left/right. It is later used to position
+      # the Guider and its arrow.
+      @target_location = () ->
+        return @target_location_cached if @target_location_cached
+        if $(document).width()/2  - @target.offset().left < 0
+          x = "right"
+        else
+          x = "left"
+        if $(document).height()/2 - @target.offset().top  < 0
+          y = "bottom"
+        else
+          y = "top"
+        @target_location_cached = { x: x, y: y }
+
+    show: (options={}) ->
+      return if @hiding
+      UIGuidersCollection.hide_all()
+      return if $.cookie("UIGuider_#{@block.attr("id")}")
+
+      options["side_arrow"]  = true                            if @block.hasClass("side_arrow")
+      options["edge"]        = @block.attr("data-target-edge") if @block.attr("data-target-edge")
+      @target = options.target                                 if options.target
+
+      @place_arrow  @target_location(), options
+      @place_guider @target_location(), options
+
+      @set_cookie()
+      @block.find(".content").html(options["content"]) if options["content"]
+      @block.fadeIn(300)
+      @state = "visible"
+
+    hide: () ->
+      return if @hiding
+      @hiding = true
+      @block.fadeOut 300, () =>
+        @hiding = false
+      @state = "hidden"
+  
+
+  class _UIGuidersCollection
+
+
+    constructor: () ->
+    
+      @ui_guiders = []
+      for g in $(".uiGuider")
+        @ui_guiders.push new UIGuider(g)
+
+      for g in @ui_guiders
+        if g.block.hasClass("autoshow")
+          setTimeout () ->
+            g.show()
+          , 1000
+
+        if g.block.hasClass("autohide")
+          g.target.bind "mouseleave", { guider: g }, (event) ->
+            event.data.guider.hide()
+        
+        if g.block.attr("data-event-name") && g.block.attr("data-event-name").length > 0
+          g.target.bind g.block.attr("data-event-name"), { guider: g }, (event) =>
+            event.data.guider.show(target: $(event.currentTarget)) unless event.data.guider.state == "visible"
+
+        g.block.find(".close").click () ->
+          g.hide()
+
+
+    find: (id) ->
+      result = null
+      for guider in @ui_guiders
+        result = guider if guider.block.attr("id") == id
+      result
+
+    hide_all: () ->
+      for guider in @ui_guiders
+        guider.hide()
+
+  window._UIGuidersCollection = _UIGuidersCollection
+  window.UIGuidersCollection  = new _UIGuidersCollection()

data/app/assets/stylesheets/ui_guiders.css.scss

@@ -0,0 +1,34 @@
+@mixin clearfix {
+  display: block;
+  &:after { content: "."; display: block; height: 0; clear: both; visibility: hidden; }
+}
+
+.uiGuider {
+
+  display: none; position: absolute; z-index: 2000;
+  width: 350px; color: #000; font-size: 0px;
+  background: #eecf84 asset_url("ui_guiders/box_bgrnd.png", "image"); background-repeat: repeat-x;
+
+  .content {
+    padding: 1em; margin: -5px 0 0 0; font-size: 11px;
+    a, a:visited { color: #a20000; }  
+  }
+
+  img.arrow           { position: relative; display: none; height: 5px; width: 13px; }
+  img.arrow.top       { @include clearfix; }
+  img.arrow.top.left  { top: -5px; left: 5px; margin: 0 0 0 0; }
+  img.arrow.top.right { top: -5px; left: -5px; float: right; margin: 0 0 0 0; }
+  img.arrow.bottom.left { top: 0; left: 5px; margin: 0 0 -5px 0; }
+  img.arrow.bottom.right { top: 0; left: -5px; float: right; margin: 0 0 -5px 0; }
+
+  img.arrow.side { width: 5px; height: 13px; margin-bottom: -13px; }
+  img.arrow.side.left  { left: -5px; }
+  img.arrow.side.right { float: right; right: -5px; }
+  
+
+  img.close { position: relative; cursor: pointer; float: right; right: 8px; top: 8px; opacity: 0.3; filter: progid:DXImageTransform.Microsoft.Alpha(Opacity=30); margin: 0 0 15px 15px; }
+  img.close:hover { opacity: 0.5; filter: progid:DXImageTransform.Microsoft.Alpha(Opacity=50); }
+
+  &.autohide img.close { display: none; }
+
+}

data/app/helpers/ui_guiders_helper.rb

@@ -0,0 +1,20 @@
+module UiGuidersHelper
+
+  def ui_guider(options={}, &block)
+    return if cookies["UIGuider_#{options[:id]}"] 
+    if block_given?
+      content = capture(&block)
+    elsif options[:template]
+      content = render(options[:template])
+    else
+      content = options[:text].html_safe
+    end
+    options[:class] = ""            unless options[:class]
+    options[:class] += " autoshow"   if     options[:autoshow]
+    options[:class] += " autohide"   if     options[:autohide]
+    options[:class] += " show_once"  if     options[:show_once]
+    options[:class] += " side_arrow" if     options[:side_arrow]
+    render :partial => "shared/ui_guider", :locals => { :content => content, :options => options }
+  end
+
+end

data/app/views/shared/_ui_guider.haml

@@ -0,0 +1,11 @@
+.uiGuider{ "data-target-element" => options[:target], "data-event-name" => options[:event], :class => options[:class], :id => options[:id], "data-target-edge" => options[:target_edge] }
+
+  = image_tag "ui_guiders/top_arrow.png", :class => "arrow top"
+  = image_tag "ui_guiders/left_arrow.png",  :class => "arrow side left"
+  = image_tag "ui_guiders/right_arrow.png", :class => "arrow side right"
+  = image_tag "ui_guiders/close_ico.png", :class => "close"
+
+  .content
+    = content
+
+  = image_tag "ui_guiders/bottom_arrow.png", :class => "arrow bottom"

data/lib/ui_guiders.rb

@@ -0,0 +1,6 @@
+module UIGuiders
+
+  class Engine < Rails::Engine
+  end
+
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: ui_guiders
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Roman Snitko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.3
+description: It's like "Guiders-JS", but easily customizable and less js-centric.
+email: roman.snitko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.markdown
+files:
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- Screenshot.png
+- VERSION
+- app/assets/images/ui_guiders/bottom_arrow.png
+- app/assets/images/ui_guiders/box_bgrnd.png
+- app/assets/images/ui_guiders/close_ico.png
+- app/assets/images/ui_guiders/left_arrow.png
+- app/assets/images/ui_guiders/right_arrow.png
+- app/assets/images/ui_guiders/top_arrow.png
+- app/assets/javascripts/lib/ui_guiders.js.coffee
+- app/assets/stylesheets/ui_guiders.css.scss
+- app/helpers/ui_guiders_helper.rb
+- app/views/shared/_ui_guider.haml
+- lib/ui_guiders.rb
+homepage: http://github.com/snitko/ui_guiders
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -648122855321890561
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: Visual guiders for website UIs.
+test_files: []