gaq 0.2.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec-dummy/log

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in gaq.gemspec
+gemspec
+
+gem 'rails', '~> 3.1.0'
+gem 'rspec-rails', '~> 2.13.2'
+
+gem 'capybara', '~> 2.0.0'
+gem 'terminal-notifier-guard'
+gem 'rb-fsevent' # used by guard for watching
+gem 'guard-rspec'
+gem 'debugger'
+
+gem 'nokogiri'

data/Guardfile

@@ -0,0 +1,23 @@
+binstubs = nil
+
+bundle_config_path = Pathname.new(__FILE__) + '../.bundle/config'
+if File.exist?(bundle_config_path)
+  yaml = File.read(bundle_config_path)
+  binstubs = YAML.load(yaml)["BUNDLE_BIN"]
+end
+
+guard 'rspec', binstubs: binstubs do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+guard 'rspec', :spec_paths => "spec-dummy/spec", cli: "-I spec-dummy/spec --tag ~dynamic",
+  binstubs: binstubs,
+  env: { 'RAILS_ENV' => 'test_static' } do
+end
+
+guard 'rspec', :spec_paths => "spec-dummy/spec", cli: "-I spec-dummy/spec --tag ~static",
+  binstubs: binstubs,
+  env: { 'RAILS_ENV' => 'test_dynamic' } do
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Thomas Stratmann
+
+MIT License
+
+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,102 @@
+# Gaq
+
+Ever wanted to push a track event from a controller? Set a custom variable from model data? Now you can.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'gaq'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gaq
+
+## Setup
+
+1. Require `gaq` from your `application.rb` and configure your web_property_id like this:
+
+    ```ruby
+    class MyApplication < Rails::Application
+      config.gaq.web_property_id = 'UA-XXYOURID-1'
+    end
+	```
+
+2. Put this in your application layout:
+
+    ```ruby
+    <%= render_gaq %>
+    ```
+
+    This inserts javascript code for initializing _gaq, your tracking events and the ga.js snippet.
+    The ga.js snippet will only be rendered in the production environment, so no real tracking happens
+    during development.
+
+3. DONE!
+
+### More setup
+
+If you want to use custom variables, configure them like this:
+
+```ruby
+  config.gaq.declare_variable :user_gender, scope: :session, slot: 1
+```
+
+If you need the _anonymizeIp feature, enable it like this:
+
+```ruby
+  config.gaq.anonymize_ip = true
+```
+
+## Usage in the controller
+
+For inserting a track event to be rendered on the current request, do
+
+```ruby
+gaq.track_event 'category', 'action', 'label'
+```
+
+If you have configured a custom variable like above, do this to set it:
+
+```ruby
+gaq.user_gender = 'female'
+```
+
+If you need to do any of these before a redirect, use these methods on `gaq.next_request`
+instead of `gaq`:
+
+```ruby
+gaq.next_request.track_event 'category', 'action', 'label'
+```
+
+This feature uses the flash for storing _gaq items between requests.
+
+## Supported tracker commands
+
+Currently, only _trackEvent and _setCustomVar is supported. However commands are easily added, so open a pull request!
+
+## Contributing
+
+1. Fork it
+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
+
+### Testing
+
+Test dependencies are declared in the Gemfile.
+All specs are run from guard.
+
+The most interesting part is the controller_handle_spec, it asserts what commands get rendered under which circumstances.
+
+There is a dummy rails application
+in `spec-dummy` for integration tests, which we need because gaq keeps state in
+the session. The integration specs are located inside of it.
+
+It has two test environments, `test_static` and `test_dynamic`. Specs tagged with
+`:static` will not be run under `test_dynamic` and vice versa. The dynamic tests are for dynamic configuration items, which is an upcoming feature that lets you configure things dynamically in the context of the running controller.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/gaq.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gaq/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "gaq"
+  gem.version       = Gaq::VERSION
+  gem.authors       = ["Thomas Stratmann"]
+  gem.email         = ["thomas.stratmann@9elements.com"]
+  gem.description   = %q{Gaq is a lightweight gem for support of pushing static and dynamic data to the _gaq from the backend.}
+  gem.summary       = %q{Renders _gaq initialization and the ga.js snippet. Supports pushing from the back end}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'actionpack'
+  gem.add_dependency 'activesupport'
+end

data/lib/gaq.rb

@@ -0,0 +1,3 @@
+require 'gaq/version'
+
+require 'gaq/railtie'

data/lib/gaq/class_cache.rb

@@ -0,0 +1,32 @@
+module Gaq
+  class ClassCache
+    Miss = Class.new(RuntimeError)
+
+    def initialize
+      @cached = Hash.new { |hash, key| hash[key] = build(key) }
+      @build_instructions = {}
+    end
+
+    def building(key, base_class, &block)
+      @build_instructions[key] = [base_class, block]
+      self
+    end
+
+    def [](key)
+      @cached[key]
+    end
+
+    def self.singleton
+      @singleton ||= new
+    end
+
+    private
+
+    def build(key)
+      raise Miss, "Nothing registered for key #{key.inspect}" unless @build_instructions.key?(key)
+      base_class, block = @build_instructions[key]
+
+      Class.new(base_class).tap(&block)
+    end
+  end
+end

data/lib/gaq/command_language.rb

@@ -0,0 +1,145 @@
+module Gaq
+  class CommandLanguage
+    attr_writer :value_coercer
+
+    def initialize
+      @descriptors = {}
+    end
+
+    CommandDescriptor = Struct.new(:signature, :name, :identifier, :sort_slot)
+
+    def knows_command(identifier)
+      @descriptors[identifier] = CommandDescriptor.new.tap do |desc|
+        desc.identifier = identifier
+        yield desc
+      end
+      self
+    end
+
+    def commands_to_flash_items(commands)
+      commands.map do |command|
+        command_to_segments(command)
+      end
+    end
+
+    # this happens to be the same, but may be different in the future
+    alias_method :commands_to_segments_for_to_json, :commands_to_flash_items
+
+    def commands_from_flash_items(flash_items)
+      flash_items.map do |flash_item|
+        descriptor, tracker_name = descriptor_and_tracker_name_from_first_segment(flash_item.first)
+        params = flash_item.drop(1).take(descriptor.signature.length)
+        Command.new(descriptor, descriptor.name, params, tracker_name)
+      end
+    end
+
+    # modifies commands
+    def sort_commands(commands)
+      sorted_pairs = commands.each_with_index.sort_by do |command, index|
+        [
+          command.descriptor.sort_slot || sort_slot_fallback,
+          index
+        ]
+      end
+      commands.replace sorted_pairs.map(&:first)
+    end
+
+    def new_command(identifier, *params)
+      descriptor = @descriptors.fetch(identifier) { raise "no command with identifier #{identifier.inspect}" }
+      params = coerce_params(params, descriptor.signature)
+
+      Command.new(descriptor, descriptor.name, params)
+    end
+
+    Command = Struct.new(:descriptor, :name, :params, :tracker_name)
+
+    private
+
+    def sort_slot_fallback
+      @sort_slot_fallback ||= @descriptors.values.map(&:sort_slot).compact.max + 1
+    end
+
+    def command_to_segments(command)
+      descriptor = command.descriptor
+
+      first_segment = first_segment_from_descriptor_and_tracker_name(descriptor, command.tracker_name)
+      [first_segment, *command.params.take(descriptor.signature.length)]
+    end
+
+    def first_segment_from_descriptor_and_tracker_name(descriptor, tracker_name)
+      [tracker_name, descriptor.name].compact.join('.')
+    end
+
+    def descriptor_and_tracker_name_from_first_segment(first_segment)
+      split = first_segment.split('.')
+      command_name, tracker_name = split.reverse
+      descriptor = @descriptors.values.find { |desc| desc.name == command_name }
+      [descriptor, tracker_name]
+    end
+
+    def coerce_params(params, signature)
+      signature = signature.take(params.length)
+      signature.zip(params).map do |type, param|
+        @value_coercer.call(type, param)
+      end
+    end
+
+    def self.declare_language_on(instance)
+      instance.knows_command(:set_account) do |desc|
+        desc.name = "_setAccount"
+        desc.signature = [:String]
+        desc.sort_slot = 0
+      end
+
+      instance.knows_command(:track_pageview) do |desc|
+        desc.name = "_trackPageview"
+        desc.signature = [:String]
+        desc.sort_slot = 2
+      end
+
+      instance.knows_command(:track_event) do |desc|
+        desc.name = "_trackEvent"
+        desc.signature = [:String, :String, :String, :Int, :Boolean]
+      end
+
+      instance.knows_command(:set_custom_var) do |desc|
+        desc.name = "_setCustomVar"
+        desc.signature = [:Int, :String, :String, :Int]
+        desc.sort_slot = 3
+      end
+
+      instance.knows_command(:anonymize_ip) do |desc|
+        desc.name = "_gat._anonymizeIp"
+        desc.signature = []
+        desc.sort_slot = 1
+      end
+    end
+
+    def self.define_transformations_on(instance)
+      instance.value_coercer = method(:coerce_value)
+    end
+
+    def self.coerce_value(type, value)
+      case type
+      when :Boolean
+        !!value
+      when :String
+        String(value)
+      when :Int
+        Integer(value)
+      when :Number
+        raise "'Number' coercion not implemented"
+        # GA docs do not tell us what that means
+      else
+        raise "Unable to coerce unknown type #{type.inspect}"
+      end
+    end
+
+    def self.singleton
+      new.tap do |result|
+        declare_language_on(result)
+        define_transformations_on(result)
+      end
+    end
+  end
+end

data/lib/gaq/configuration.rb

@@ -0,0 +1,159 @@
+require 'forwardable'
+require 'active_support/ordered_options'
+
+module Gaq
+  class Configuration
+    attr_reader :rails_config, :variables
+
+    RAILS_CONFIG_ACCESSORS = [:anonymize_ip, :render_ga_js]
+    attr_accessor(*RAILS_CONFIG_ACCESSORS)
+
+    VariableException = Class.new(RuntimeError)
+
+    Variable = Struct.new(:slot, :name, :scope) do
+      SCOPE_MAP = {
+        nil => 3, #we allow for a default @TODO check documentation
+
+        :visitor => 1,
+        :session => 2,
+        :page => 3,
+
+        1 => 1,
+        2 => 2,
+        3 => 3
+      }
+
+      def initialize(slot, name, scope)
+        super(slot, name)
+        set_scope scope
+      end
+
+      private
+
+      def set_scope(scope)
+        self.scope = SCOPE_MAP.fetch(scope) do
+          raise VariableException, "unknown scope #{scope.inspect}"
+        end
+      end
+    end
+
+    def initialize
+      default_tracker_config = TrackerConfig.new(nil)
+      @default_tracker_rails_config = default_tracker_config.rails_config
+
+      @tracker_configs = { nil => default_tracker_config }
+      @rails_config = RailsConfig.new(self, default_tracker_config)
+      @variables = {}
+    end
+
+    def declare_variable(name, options = {})
+      # @TODO deprecate use without slot given
+      # We just code like it's always given here
+      slot = options[:slot]
+      # @TODO raise when slot off limits
+      raise VariableException, "Already have a variable at that slot" if
+        @variables.find { |_, var| var.slot == slot }
+      raise VariableException, "Already have a variable of that name" if
+        @variables.find { |_, var| var.name == name }
+
+      variable = Variable.new(slot, name, options[:scope])
+      @variables[name] = variable
+    end
+
+    def register_tracker_name(name)
+      name = name.to_s
+      # @TODO check for collision, assert name format
+
+      raise "duplicate tracker name" if @tracker_configs.key?(name)
+      @tracker_configs[name] = TrackerConfig.new(name)
+    end
+
+    def tracker_rails_config(name) # name can be nil -> default tracker
+      name = name.to_s unless name.nil?
+      tracker_config = @tracker_configs.fetch(name) { raise "No tracker by that name (#{name.inspect})" }
+      tracker_config.rails_config
+    end
+
+    def tracker_config(name)
+      @tracker_configs[name]
+    end
+
+    def tracker_names
+      @tracker_configs.keys
+    end
+
+    def render_ga_js?(environment)
+      environment = environment.to_s
+
+      case render_ga_js
+      when TrueClass, FalseClass
+        render_ga_js
+      when Array, Symbol
+        Array(render_ga_js).map(&:to_s).include? environment
+      else
+        render_ga_js
+      end
+    end
+
+    class TrackerConfig
+      attr_reader :rails_config, :tracker_name
+
+      RAILS_CONFIG_ACCESSORS = [:web_property_id, :track_pageview]
+      attr_accessor(*RAILS_CONFIG_ACCESSORS)
+      alias_method :track_pageview?, :track_pageview
+
+      def initialize(tracker_name)
+        @tracker_name = tracker_name
+
+        @track_pageview = true
+        @rails_config = RailsConfig.new(self)
+
+        @web_property_id = 'UA-XUNSET-S'
+      end
+
+      class RailsConfig
+        extend Forwardable
+        def_delegators :@config, *RAILS_CONFIG_ACCESSORS.map { |m| "#{m}=" }
+
+        def initialize(config)
+          @config = config
+        end
+      end
+    end
+
+    class RailsConfig
+      extend Forwardable
+      def_delegators :@config, :declare_variable,
+        *Configuration::RAILS_CONFIG_ACCESSORS.map { |m| "#{m}=" }
+      def_delegators :@default_tracker_rails_config,
+        *TrackerConfig::RAILS_CONFIG_ACCESSORS.map { |m| "#{m}=" }
+
+      def initialize(config, default_tracker_rails_config)
+        @config = config
+
+        @default_tracker_rails_config = default_tracker_rails_config
+
+        @anonymize_ip = false
+        @render_ga_js = :production
+      end
+
+
+      def additional_trackers=(array)
+        raise "you can only do this once" if @trackers_set
+        @trackers_set = true
+
+        array.each { |name| @config.register_tracker_name(name) }
+      end
+
+      def tracker(name)
+        @config.tracker_rails_config(name)
+      end
+    end
+
+    class << self
+      def singleton
+        @singleton ||= new
+      end
+    end
+  end
+end