markcatley-google_analytics 1.0.20080720 → 1.0.20080822

data/README

@@ -18,7 +18,7 @@ If you want to disable the code insertion for particular pages, add the followin
 
 If you are running rails 2.1 or above add install this by adding:
     
-    config.gem 'markcatley-google_analytics', :lib => 'rubaidh/google_analytics', :source => 'http://gems.github.com'
+    config.gem 'rubaidh-google_analytics', :lib => 'rubaidh/google_analytics', :source => 'http://gems.github.com'
     
 and run:
 
@@ -98,4 +98,22 @@ configuration:
     end
 
 The above Capistrano recipe will almost certainly need some adjustments based
-on how you run your deployments, but you should get the idea.
+on how you run your deployments, but you should get the idea.
+
+OVERRIDING APPLICATION-WIDE VALUES
+
+If you're using one Rails application to serve pages across multiple domains, you
+may wish to override the domain and tracker ID values on a controller-by-controller or 
+view-by-view basis. You can do this by setting the override_domain_name and 
+override_tracker_id properties. These properties are automatically reset after
+each use, so the values you set for domain_name and tracker_id (usually in an
+initializer) will apply to all other requests.
+
+before_filter :local_analytics
+
+def local_analytics
+  Rubaidh::GoogleAnalytics.override_domain_name  = 'foo.com'
+  Rubaidh::GoogleAnalytics.override_tracker_id  = 'UA-123456-7'
+end
+
+See the documentation for the GoogleAnalytics class for other configuration options.

data/lib/rubaidh/google_analytics.rb

@@ -5,10 +5,9 @@ module Rubaidh # :nodoc:
     end
     
     # An after_filter to automatically add the analytics code.
-    # Add the code at the top of the page to support calls to _trackPageView 
-    #   (see http://www.google.com/support/googleanalytics/bin/answer.py?answer=55527&topic=11006)
-    # If you're not going to use the link_to_tracked view helpers, you can set Rubaidh::GoogleAnalytics.defer_load = true
-    #  to load the codel at the bottom of the page
+    # If you intend to use the link_to_tracked view helpers, you need to set Rubaidh::GoogleAnalytics.defer_load = false
+    # to load the code at the top of the page
+    # (see http://www.google.com/support/googleanalytics/bin/answer.py?answer=55527&topic=11006)
     def add_google_analytics_code
       if GoogleAnalytics.defer_load
         response.body.sub! '</body>', "#{google_analytics_code}</body>" if response.body.respond_to?(:sub!)
@@ -20,57 +19,126 @@ module Rubaidh # :nodoc:
 
   class GoogleAnalyticsConfigurationError < StandardError; end
 
+  # The core functionality to connect a Rails application
+  # to a Google Analytics installation.
+  #
+  # The +GoogleAnalytics+ class has a variety of class attributes for configuration:
+  #
+  # * tracker_id (required)
+  # 
+  # Specify the Google Analytics ID for this web site. This can be found
+  # as the value of +_getTracker+ if you are using the new (ga.js) tracking
+  # code, or the value of +_uacct+ if you are using the old (urchin.js)
+  # tracking code.
+  #
+  # * domain_name
+  #
+  # Specify a different domain name from the default. You'll want to use
+  # this if you have several subdomains that you want to combine into
+  # one report. See the Google Analytics documentation for more
+  # information.
+  #
+  # * legacy_mode
+  #
+  # Specify whether the legacy Google Analytics code should be used. By
+  # default, the new Google Analytics code is used.
+  #
+  # * analytics_url
+  #
+  # I can't see why you'd want to do this, but you can always change the
+  # analytics URL. This is only applicable in legacy mode.
+  #
+  # * analytics_ssl_url
+  #
+  # I can't see why you'd want to do this, but you can always change the
+  # analytics URL (ssl version). This is only applicable in legacy mode.
+  #
+  # * environments
+  #
+  # The environments in which to enable the Google Analytics code. Defaults
+  # to 'production' only. Supply an array of environment names to change this.
+  #
+  # * formats
+  #
+  # The formats for which to add.  Defaults to +:html+ only. Supply an array
+  # of formats to change this.
+  #
+  # * defer_load
+  #
+  # Set this to true (the default) if you want to load the Analytics javascript at 
+  # the bottom of page. Set this to false if you want to load the Analytics 
+  # javascript at the top of the page. The page will render faster if you set this to
+  # true, but that will break the linking functions in Rubaidh::GoogleAnalyticsViewHelper.
+  #
+  # * local_javascript
+  #
+  # Set this to true to use a local copy of the ga.js (or urchin.js) file.
+  # This gives you the added benefit of serving the JS directly from your
+  # server, which in case of a big geographical difference between your server
+  # and Google's can speed things up for your visitors. Use the 
+  # 'google_analytics:update' rake task to update the local JS copies.
+  #
+  # * override_domain_name
+  #
+  # Set this to override the initialized domain name for a single render. Useful
+  # when you're serving to multiple hosts from a single codebase. Typically you'd 
+  # set up a before filter in the appropriate controller:
+  #    before_filter :override_domain_name
+  #    def override_domain_name
+  #      Rubaidh::GoogleAnalytics.override_domain_name  = 'foo.com'
+  #   end
+  #
+  # * override_tracker_id
+  #
+  # Set this to override the initialized tracker ID for a single render. Useful
+  # when you're serving to multiple hosts from a single codebase. Typically you'd 
+  # set up a before filter in the appropriate controller:
+  #    before_filter :override_tracker_id
+  #    def override_tracker_id
+  #      Rubaidh::GoogleAnalytics.override_tracker_id  = 'UA-123456-7'
+  #   end
+  #
+  # * override_trackpageview
+  #
+  # Set this to override the automatically generated path to the page in the
+  # Google Analytics reports for a single render. Typically you'd set this up on a 
+  # controller-by-controller basis:
+  #    def show
+  #      Rubaidh::GoogleAnalytics.override_trackpageview = "path_to_report"
+  #      ...
   class GoogleAnalytics
-    # Specify the Google Analytics ID for this web site.  This can be found
-    # as the value of +_uacct+ in the Javascript excerpt
+  
     @@tracker_id = nil
-    cattr_accessor :tracker_id
+    cattr_accessor :tracker_id  
 
-    # Specify a different domain name from the default.  You'll want to use
-    # this if you have several subdomains that you want to combine into
-    # one report.  See the Google Analytics documentation for more
-    # information.
     @@domain_name = nil
     cattr_accessor :domain_name
 
-    # Specify whether the legacy Google Analytics code should be used.
     @@legacy_mode = false
     cattr_accessor :legacy_mode
     
-    # I can't see why you'd want to do this, but you can always change the
-    # analytics URL.  This is only applicable in legacy mode.
     @@analytics_url = 'http://www.google-analytics.com/urchin.js'
     cattr_accessor :analytics_url
 
-    # I can't see why you'd want to do this, but you can always change the
-    # analytics URL (ssl version).  This is only applicable in legacy mode.
     @@analytics_ssl_url = 'https://ssl.google-analytics.com/urchin.js'
     cattr_accessor :analytics_ssl_url
 
-    # The environments in which to enable the Google Analytics code.  Defaults
-    # to 'production' only.
     @@environments = ['production']
     cattr_accessor :environments
     
-    # The formats for which to add.  Defaults
-    # to :html only.
     @@formats = [:html]
     cattr_accessor :formats
 
-    # Set this to true if you want to load the Analytics javascript at the bottom of
-    # each page rather than at the top. This may result in faster page render times, 
-    # but may break link_to_tracked functionality.
     @@defer_load = true
     cattr_accessor :defer_load
     
-    # Set this to true to use a local copy of the ga.js (or urchin.js) file.
-    # This gives you the added benefit of serving the JS directly from your
-    # server, which in case of a big geographical difference between your server
-    # and Google's can speed things up for your visitors. Use the 
-    # 'google_analytics:update' rake task to update the local JS copies.
     @@local_javascript = false
     cattr_accessor :local_javascript
     
+    cattr_accessor :override_domain_name
+    cattr_accessor :override_tracker_id
+    cattr_accessor :override_trackpageview
+    
     # Return true if the Google Analytics system is enabled and configured
     # correctly for the specified format
     def self.enabled?(format)
@@ -78,10 +146,16 @@ module Rubaidh # :nodoc:
       environments.include?(RAILS_ENV) && formats.include?(format.to_sym)
     end
     
+    # Construct the javascript code to be inserted on the calling page. The +ssl+
+    # parameter can be used to force the SSL version of the code in legacy mode only.
     def self.google_analytics_code(ssl = false)
       return legacy_google_analytics_code(ssl) if legacy_mode
 
       extra_code = domain_name.blank? ? nil : "pageTracker._setDomainName(\"#{domain_name}\");"
+      if !override_domain_name.blank?
+        extra_code = "pageTracker._setDomainName(\"#{override_domain_name}\");"
+        self.override_domain_name = nil
+      end
       
       code = if local_javascript
         <<-HTML
@@ -100,27 +174,33 @@ module Rubaidh # :nodoc:
       code << <<-HTML
       <script type="text/javascript">
       <!--//--><![CDATA[//><!--
-      var pageTracker = _gat._getTracker('#{tracker_id}');
+      var pageTracker = _gat._getTracker('#{request_tracker_id}');
       #{extra_code}
       pageTracker._initData();
-      pageTracker._trackPageview();
+      pageTracker._trackPageview(#{request_tracked_path});
       //--><!]]>
       </script>
       HTML
     end
 
-    # Run the legacy version of the Google Analytics code.
+    # Construct the legacy version of the Google Analytics code. The +ssl+
+    # parameter specifies whether or not to return the SSL version of the code.
     def self.legacy_google_analytics_code(ssl = false)
       extra_code = domain_name.blank? ? nil : "_udn = \"#{domain_name}\";"
+      if !override_domain_name.blank?
+        extra_code = "_udn = \"#{override_domain_name}\";"
+        self.override_domain_name = nil
+      end
+
       url = legacy_analytics_js_url(ssl)
 
       code = <<-HTML
       <script src="#{url}" type="text/javascript">
       </script>
       <script type="text/javascript">
-      _uacct = "#{tracker_id}";
+      _uacct = "#{request_tracker_id}";
       #{extra_code}
-      urchinTracker();
+      urchinTracker(#{request_tracked_path});
       </script>
       HTML
     end
@@ -133,9 +213,24 @@ module Rubaidh # :nodoc:
         ssl ? analytics_ssl_url : analytics_url
       end
     end
+
+    # Determine the tracker ID for this request
+    def self.request_tracker_id
+      use_tracker_id = override_tracker_id.blank? ? tracker_id : override_tracker_id
+      self.override_tracker_id = nil
+      use_tracker_id
+    end
+    
+    # Determine the path to report for this request
+    def self.request_tracked_path
+      use_tracked_path = override_trackpageview.blank? ? '' : "'#{override_trackpageview}'"
+      self.override_trackpageview = nil
+      use_tracked_path
+    end
+    
   end
-  
-  class LocalAssetTagHelper
+
+  class LocalAssetTagHelper # :nodoc:
     # For helping with local javascripts
     include ActionView::Helpers::AssetTagHelper
   end

data/lib/rubaidh/view_helpers.rb

@@ -1,23 +1,41 @@
 module Rubaidh
-  module GoogleAnalyticsViewHelper #:nodoc:
+  # Collection of methods similar to the ones in ActionView::Helpers::UrlHelper,
+  # with the addition of outbound link tracking. See the Google Analytics help
+  # at http://www.google.com/support/googleanalytics/bin/answer.py?answer=55527
+  # for more information on outbound link tracking.
+  module GoogleAnalyticsViewHelper
+    # Creates a link tag of the given +name+ using a URL created by the set of +options+,
+    # with outbound link tracking under +track_path+ in Google Analytics. The +html_options+
+    # will accept a hash of attributes for the link tag.
     def link_to_tracked(name, track_path = "/", options = {}, html_options = {})
       raise AnalyticsError.new("You must set Rubaidh::GoogleAnalytics.defer_load = false to use outbound link tracking") if GoogleAnalytics.defer_load == true
       html_options.merge!({:onclick => tracking_call(track_path)})
       link_to name, options, html_options
     end
     
+    # Creates a link tag of the given +name+ using a URL created by the set of +options+
+    # if +condition+ is true, with outbound link tracking under +track_path+ in Google Analytics. 
+    # The +html_options+ will accept a hash of attributes for the link tag.
     def link_to_tracked_if(condition, name, track_path = "/", options = {}, html_options = {}, &block)
       raise AnalyticsError.new("You must set Rubaidh::GoogleAnalytics.defer_load = false to use outbound link tracking") if GoogleAnalytics.defer_load == true
       html_options.merge!({:onclick => tracking_call(track_path)})
       link_to_unless !condition, name, options, html_options, &block
     end
     
+    # Creates a link tag of the given +name+ using a URL created by the set of +options+
+    # unless +condition+ is true, with outbound link tracking under +track_path+ in Google Analytics. 
+    # The +html_options+ will accept a hash of attributes for the link tag.
     def link_to_tracked_unless(condition, name, track_path = "/", options = {}, html_options = {}, &block)
       raise AnalyticsError.new("You must set Rubaidh::GoogleAnalytics.defer_load = false to use outbound link tracking") if GoogleAnalytics.defer_load == true
       html_options.merge!({:onclick => tracking_call(track_path)})
       link_to_unless condition, name, options, html_options, &block
     end
     
+    # Creates a link tag of the given +name+ using a URL created by the set of +options+
+    # unless the current request URI is the same as the link's, with outbound link tracking 
+    # under +track_path+ in Google Analytics. If the request URI is the same as the link 
+    # URI, only the name is returned, or the block is yielded, if one exists.
+    # The +html_options+ will accept a hash of attributes for the link tag.
     def link_to_tracked_unless_current(name, track_path = "/", options = {}, html_options = {}, &block)
       raise AnalyticsError.new("You must set Rubaidh::GoogleAnalytics.defer_load = false to use outbound link tracking") if GoogleAnalytics.defer_load == true
       html_options.merge!({:onclick =>tracking_call(track_path)})
@@ -36,6 +54,8 @@ private
     
   end
   
+  # Error raised by tracking methods if Rubaidh::GoogleAnalytics.defer_load is not configured
+  # properly to enable tracking.
   class AnalyticsError < StandardError
     attr_reader :message
     

data/test/google_analytics_test.rb

@@ -1,8 +1,117 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
 require 'test/unit'
+require 'rubygems'
+require 'mocha'
 
 class GoogleAnalyticsTest < Test::Unit::TestCase
-  # Replace this with your real tests.
-  def test_this_plugin
-    flunk
+  def setup
+    @ga = Rubaidh::GoogleAnalytics.new
+    @ga.tracker_id = "the tracker id"
   end
+  
+  def test_createable
+    assert_not_nil(@ga)
+  end
+  
+  def test_domain_name_defaults_to_nil
+    assert_nil(@ga.domain_name)
+  end
+  
+  def test_legacy_mode_defaults_to_false
+    assert_equal(false, @ga.legacy_mode)
+  end
+  
+  def test_default_analytics_url
+    assert_equal("http://www.google-analytics.com/urchin.js", @ga.analytics_url)
+  end
+  
+  def test_default_analytics_ssl_url
+    assert_equal('https://ssl.google-analytics.com/urchin.js', @ga.analytics_ssl_url)
+  end
+  
+  def test_default_environments
+    assert_equal(false, @ga.environments.include?('test'))
+    assert_equal(false, @ga.environments.include?('development'))
+    assert_equal(true, @ga.environments.include?('production'))
+  end
+  
+  def test_default_formats
+    assert_equal(false, @ga.formats.include?(:xml))
+    assert_equal(true, @ga.formats.include?(:html))
+  end
+
+  def test_defer_load_defaults_to_true
+    assert_equal(true, @ga.defer_load)
+  end
+  
+  def test_local_javascript_defaults_to_false
+    assert_equal(false, @ga.local_javascript)
+  end
+  
+  # test self.enabled
+  def test_enabled_requires_tracker_id
+    Rubaidh::GoogleAnalytics.stubs(:tracker_id).returns(nil)
+    assert_raise(Rubaidh::GoogleAnalyticsConfigurationError) { Rubaidh::GoogleAnalytics.enabled?(:html) }
+  end
+  
+  def test_enabled_requires_analytics_url
+    Rubaidh::GoogleAnalytics.stubs(:analytics_url).returns(nil)
+    assert_raise(Rubaidh::GoogleAnalyticsConfigurationError) { Rubaidh::GoogleAnalytics.enabled?(:html) }
+  end
+  
+  def test_enabled_returns_false_if_current_environment_not_enabled
+    assert_equal(false, Rubaidh::GoogleAnalytics.enabled?(:html))
+  end
+  
+  def test_enabled_with_default_format
+    Rubaidh::GoogleAnalytics.stubs(:environments).returns(['test'])
+    assert_equal(true, Rubaidh::GoogleAnalytics.enabled?(:html))
+  end
+  
+  def test_enabled_with_not_included_format
+    Rubaidh::GoogleAnalytics.stubs(:environments).returns(['test'])
+    assert_equal(false, Rubaidh::GoogleAnalytics.enabled?(:xml))
+  end
+  
+  def test_enabled_with_added_format
+    Rubaidh::GoogleAnalytics.stubs(:environments).returns(['test'])
+    Rubaidh::GoogleAnalytics.stubs(:formats).returns([:xml])
+    assert_equal(true, Rubaidh::GoogleAnalytics.enabled?(:xml))
+  end
+
+  # test request_tracker_id
+  def test_request_tracker_id_without_override
+    Rubaidh::GoogleAnalytics.stubs(:tracker_id).returns("1234")
+    assert_equal("1234", Rubaidh::GoogleAnalytics.request_tracker_id)
+  end
+  
+  def test_request_tracker_id_with_override
+    Rubaidh::GoogleAnalytics.stubs(:tracker_id).returns("1234")
+    Rubaidh::GoogleAnalytics.override_tracker_id = "4567"
+    assert_equal("4567", Rubaidh::GoogleAnalytics.request_tracker_id)
+  end
+  
+  def test_request_tracker_id_resets_override
+    Rubaidh::GoogleAnalytics.override_tracker_id = "4567"
+    Rubaidh::GoogleAnalytics.stubs(:tracker_id).returns("1234")
+    foo = Rubaidh::GoogleAnalytics.request_tracker_id
+    assert_nil(Rubaidh::GoogleAnalytics.override_tracker_id)
+  end
+  
+  # test request_tracked_path
+  def test_request_tracked_path_without_override
+    assert_equal('', Rubaidh::GoogleAnalytics.request_tracked_path)
+  end
+  
+  def test_request_tracked_path_with_override
+    Rubaidh::GoogleAnalytics.override_trackpageview = "/my/path"
+    assert_equal("'/my/path'", Rubaidh::GoogleAnalytics.request_tracked_path)
+  end
+  
+  def test_request_tracked_path_resets_override
+    Rubaidh::GoogleAnalytics.override_trackpageview = "/my/path"
+    foo = Rubaidh::GoogleAnalytics.request_tracked_path
+    assert_nil(Rubaidh::GoogleAnalytics.override_trackpageview)
+  end
+  
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: markcatley-google_analytics
 version: !ruby/object:Gem::Version 
-  version: 1.0.20080720
+  version: 1.0.20080822
 platform: ruby
 authors: 
 - Graeme Mathieson
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-08 00:00:00 -07:00
+date: 2008-08-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -38,7 +38,8 @@ files:
 - test/view_helpers_test.rb
 - lib/rubaidh/google_analytics.rb
 - lib/rubaidh/view_helpers.rb
-has_rdoc: false
+- task/google_analytics.rake
+has_rdoc: true
 homepage: http://github.com/rubaidh/google_analytics/tree/master
 post_install_message: 
 rdoc_options: []