rubango 0.1.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Jonah Honeyman
+
+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.md

@@ -0,0 +1,84 @@
+rubango
+================
+
+A ruby API wrapper for integrating your rails application with [Totango](http://www.totango.com).
+
+Installation
+------------
+
+    gem install rubango # use 'totango' when require-ing
+
+Usage
+-----
+
+First, build your client with your API id:
+
+    Totango.srv_id "YOUR_ID_GOES_HERE"
+
+By default, Totango will not make remote calls. It will print a debug message about the URL that would be getting hit. This message can be annoying when testing. To turn the message off, use `Totango::Config`:
+
+    Totango::Config[:suppress_output] = true
+
+To make the remote call to totango.com you must turn the tracker on:
+
+    Totango.on! # you will probably only want to do this in production mode.
+
+You now interact with `Totango.client` to do your bidding:
+
+    Totango.client.track({
+      :organization => "Current organization",
+      :user => "Current user",
+      :activity => "Current activity",
+      :module => "Current module"
+    })
+
+There is also the option for integration with different ruby frameworks.
+
+### Rails
+
+    class ApplicationController < ActionController::Base
+      include Totango::Adapters::Rails
+
+      #...
+    end
+
+That will build your tracking code based around a couple of sane defaults. By default it will set the current module to `params[:controller]` and activity to `params[:action]`. If you wish to override the defaults you can do so in your controllers:
+
+    class MyController < ApplictationController
+      sp_default :activity, "Whatever you want here"
+      # You may also send a Proc object as the value so that it is
+      # evaluated in the context of the current controller. For example:
+      sp_default :user, proc { method_to_determine_current_user }
+    end
+
+To track different actions, you must now tell Totango which actions you would like to track:
+
+    class MyController < ApplictationController
+      track :index
+      track :show, "Override default activity text here"
+      track :edit, :user => "override other defaults in a hash"
+      track :destroy, :if => proc { params[:my_boolean] } # Use conditionals to only run tracking based on the eval'd code in the Proc object
+    end
+
+### Rolling your own adapter
+
+There are currently adapters for rails and merb, but it is simple to write your own adapter
+
+    module MySPAdapter
+      extend Totango::Adapters::Base
+
+      register_adapter :my_adapter
+      hook_method :before_hook      # Hook method name that will be called before or after each action
+      action_finder :action_name    # Method that determines the current action being hit
+
+      # You can set defaults from here that will be set on the controller class
+      # that includes your adapter and all of its subclasses
+      sp_default :activity, proc {action_name}
+      sp_default :module, proc {controller_name}
+    end
+
+TODO
+----
+
+* Adapter tests
+* JS client integration

data/lib/totango/adapter.rb

@@ -0,0 +1,9 @@
+module Totango
+  class << self; attr_accessor :adapter end
+
+  class Adapter
+    attr_accessor :name, :hook, :action_finder
+  end
+end
+
+

data/lib/totango/adapters/base.rb

@@ -0,0 +1,41 @@
+module Totango
+  module Adapters
+    module Base
+      def self.extended(base)
+        base.instance_variable_set :@__current_adapter__, Totango::Adapter.new
+      end
+
+      private
+
+      def included(klass)
+        Totango.adapter = adapter
+        klass.send(:include, Totango::Resource) unless klass.include?(Totango::Resource)
+        (@defaults || []).each do |e|
+          klass.sp_default *e
+        end
+      end
+
+      def sp_default(k, v)
+        @defaults ||= []
+        @defaults << [k,v]
+      end
+
+      def register_adapter(name)
+        adapter.name = name
+      end
+
+      def hook_method(name)
+        adapter.hook = name
+      end
+
+      def action_finder(name)
+        adapter.action_finder = name
+      end
+
+      def adapter
+        @__current_adapter__
+      end
+    end
+  end
+end
+

data/lib/totango/adapters/merb.rb

@@ -0,0 +1,15 @@
+module Totango
+  module Adapters
+    module Merb
+      extend Totango::Adapters::Base
+
+      register_adapter :merb
+      hook_method :after
+      action_finder :action_name
+
+      sp_default :activity, proc { action_name }
+      sp_default :module,   proc { controller_name }
+    end
+  end
+end
+

data/lib/totango/adapters/rails.rb

@@ -0,0 +1,15 @@
+module Totango
+  module Adapters
+    module Rails
+      extend Totango::Adapters::Base
+
+      register_adapter :rails
+      hook_method :after_filter
+      action_finder :action_name
+
+      sp_default :activity, proc { action_name }
+      sp_default :module,   proc { controller_name }
+    end
+  end
+end
+

data/lib/totango/arg_parser.rb

@@ -0,0 +1,60 @@
+module Totango
+  class InvalidParamError < StandardError; end
+
+  class ArgParser
+    class <<self
+      attr_reader :named_args
+
+      def parse(args)
+        new.tap do |parser|
+          args.each do |arg, val|
+            param = registered_args[arg]
+            raise InvalidParamError, "'#{arg}' does not map to a valid param" unless param
+
+            parser[param] = val
+          end
+        end
+      end
+
+      private
+
+      def parses_arg(name, *aliases)
+        register_named_arg! name
+        attr_reader name
+
+        aliases.unshift(name).each do |argname|
+          registered_args[argname] = name
+        end
+      end
+
+      def registered_args
+        @__registered_args__ ||= {}
+      end
+
+      def register_named_arg!(name)
+        @named_args ||= []
+        @named_args << name
+      end
+    end
+
+    parses_arg :sdr_a, :a, :act, :activity
+    parses_arg :sdr_o, :o, :org, :organization
+    parses_arg :sdr_m, :m, :mod, :module
+    parses_arg :sdr_u, :u, :user
+
+    def to_params
+      ArgParser.named_args.map do |arg|
+        [arg, CGI.escape(self[arg].to_s)].join("=")
+      end.join("&")
+    end
+
+    def [](arg)
+      instance_variable_get :"@#{arg}"
+    end
+
+    def []=(arg, val)
+      instance_variable_set :"@#{arg}", val
+    end
+  end
+end
+

data/lib/totango/client.rb

@@ -0,0 +1,55 @@
+module Totango
+  BASE_URI = "http://sdr.totango.com/pixel.gif/?sdr_s=".freeze unless self.const_defined?(:BASE_URI)
+
+  class NoClientError < StandardError; end
+
+  class << self
+    attr_reader :client
+
+    def track(data)
+      raise NoClientError, "You must set the current client first" unless client
+      client.track(data)
+    end
+
+    def srv_id(srv_id)
+      @client = Client.new(srv_id)
+    end
+
+    def on?
+      Config[:on]
+    end
+
+    def on!
+      Config[:on] = true
+    end
+  end
+
+  class Client
+    def initialize(srv_id)
+      @srv_id = srv_id
+    end
+
+    def track(data={})
+      url = build_url(data)
+
+      if Totango.on?
+        Thread.new do
+          begin
+            open(url)
+          rescue => e
+            STDERR.puts "[Totango] ERROR making call to Totango: #{e.class} ~> #{e.message}"
+          end
+        end
+      else
+        unless Config[:suppress_output]
+          puts "[Totango] Fake call to #{url}. To make a real call, run Totango.on!"
+        end
+      end
+    end
+
+    def build_url(data)
+      [BASE_URI, @srv_id, "&", ArgParser.parse(data).to_params].join
+    end
+  end
+end
+

data/lib/totango/config.rb

@@ -0,0 +1,25 @@
+module Totango
+  class Config
+    class <<self
+      def defaults
+        @defaults ||= {
+          :on => false,
+          :suppress_output => false
+        }
+      end
+
+      def [](setting)
+        defaults[setting]
+      end
+
+      def []=(setting, value)
+        defaults[setting] = value
+      end
+
+      def use
+        yield defaults
+      end
+    end
+  end
+end
+

data/lib/totango/resource.rb

@@ -0,0 +1,80 @@
+module Totango
+  class NoAdapterError < StandardError; end
+
+  module Resource
+    @sp_defaults = {
+      :organization => "Default Org",
+      :user => "Default User",
+      :activity => "Default Activity",
+      :module => "Default Module"
+    }
+
+    module ClassMethods
+      def sp_default(key, val)
+        raise ArgumentError, "Key #{key.inspect} is not a valid option" unless @sp_defaults.keys.member?(key)
+
+        sp_defaults[key] = val
+      end
+
+      # action<Symbol>:: Action to track
+      # opts<Hash>:: Override defaults and set conditional tracking
+      def track(action, *opts)
+        tracker = Totango::Tracker.new(action, *opts)
+        sp_trackers << tracker unless sp_trackers.find {|t| t.action.to_s == action.to_s}
+      end
+
+      def sp_trackers
+        @__sp_trackers__ ||= []
+      end
+
+      private
+
+      def inherited(klass)
+        super(klass)
+        klass.instance_variable_set :@sp_defaults, @sp_defaults.dup
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+      class << base; attr_reader :sp_defaults end
+      base.instance_variable_set :@sp_defaults, @sp_defaults.dup
+      base.send(Totango.adapter.hook, :sp_run)
+    end
+
+    private
+
+    def sp_run
+      raise NoAdapterError, "No adapter has been set" unless Totango.adapter
+
+      tracker = self.class.sp_trackers.find do |t|
+        t.action.to_s == send(Totango.adapter.action_finder).to_s
+      end
+
+      return unless tracker
+
+      if condition = tracker.opts[:if]
+        return unless instance_eval(&condition)
+      end
+
+      Totango.track({
+        :o => sp_opt(tracker, :organization),
+        :a => sp_opt(tracker, :activity),
+        :m => sp_opt(tracker, :module),
+        :u => sp_opt(tracker, :user)
+      })
+    end
+
+    def sp_opt(tracker, param)
+      value = tracker.opts[param] || sp_defaults[param]
+
+      return instance_eval(&value) if Proc === value
+      value
+    end
+
+    def sp_defaults
+      self.class.sp_defaults
+    end
+  end
+end
+

data/lib/totango/tracker.rb

@@ -0,0 +1,23 @@
+module Totango
+  class Tracker
+    def initialize(action, *opts)
+      @action = action
+      activity = opts.shift
+      @opts = opts.empty? ? {} : opts.shift
+
+      return unless activity
+
+      case activity
+      when String
+        @opts[:activity] = activity
+      when Hash
+        @opts = activity
+      else
+        raise ArgumentError, "activity must be a String or Hash"
+      end
+    end
+
+    attr_reader :action, :opts
+  end
+end
+

data/lib/totango/version.rb

@@ -0,0 +1,3 @@
+module Totango
+  VERSION = "0.1.2" unless defined?(::Totango::VERSION)
+end

data/lib/totango.rb

@@ -0,0 +1,16 @@
+lib = File.expand_path('../../lib/', __FILE__) 
+$:.unshift(lib) unless $:.include?(lib)
+
+require 'open-uri'
+require 'cgi'
+
+require 'totango/config'
+require 'totango/client'
+require 'totango/arg_parser'
+require 'totango/tracker'
+require 'totango/adapter'
+require 'totango/resource'
+require 'totango/adapters/base'
+require 'totango/adapters/merb'
+require 'totango/adapters/rails'
+

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: rubango
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 2
+  version: 0.1.2
+platform: ruby
+authors: 
+- jonah honeyman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-09 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Enables easy integration of Totango tracking, with options for different ruby web frameworks
+email: 
+- jonah@honeyman.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/totango/version.rb
+- lib/totango/arg_parser.rb
+- lib/totango/client.rb
+- lib/totango/resource.rb
+- lib/totango/adapters/base.rb
+- lib/totango/adapters/rails.rb
+- lib/totango/adapters/merb.rb
+- lib/totango/adapter.rb
+- lib/totango/tracker.rb
+- lib/totango/config.rb
+- lib/totango.rb
+- LICENSE
+- README.md
+has_rdoc: true
+homepage: https://github.com/jonuts/rubango
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: rubango
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: API wrapper for Totango tracking integration
+test_files: []
+