garb 0.8.5 → 0.9.0

data/README.md

@@ -6,12 +6,14 @@ Garb
 Important Changes
 =================
 
-  I've started to work on a new module for reporting. You can see that work
-  in lib/garb/model.rb. This will be the API to replace both Garb::Resource
-  and Garb::Report. However, it isn't complete yet, so I would advise against
-  using it right now. Resource and Report will be deprecated around 0.9.0 and
-  I'd like to remove them for 1.0.0. I will start this process after I've
-  updated the documentation and I feel that Garb::Model is in a solid place.
+  With The release of version 0.9.0 I have officially deprecated Garb::Report, Garb::Resource,
+  Garb::Profile, and Garb::Account. Garb::Report and Garb::Resource should be replaced by Garb::Model.
+  Garb::Profile and Garb::Account are supplanted by their Garb::Management::* counterparts.
+  
+  I'll be working hard to update the documentation over the next day or so to highlight all of the
+  old features in the new classes, as well as any new features brought by the new classes. If you
+  are looking for something in particular, please open an issue and I will try to prioritize these
+  requests.
 
   Please read CHANGELOG
 
@@ -35,47 +37,39 @@ OAuth Access Token
 
     > Garb::Session.access_token = access_token # assign from oauth gem
 
-Accounts
+Accounts, WebProperties, Profiles, and Goals
 --------
 
-    > Garb::Account.all
+    > Garb::Management::Account.all
+    > Garb::Management::WebProperty.all
+    > Garb::Management::Profile.all
+    > Garb::Management::Goal.all
 
-Profiles
+Profiles for a UA- Number (a WebProperty)
 --------
 
-    > Garb::Account.first.profiles
-    
-    > Garb::Profile.first('UA-XXXX-XX')
-    
-    > Garb::Profile.all
-    > profile = Garb::Profile.all.first
+    > profile = profile = Garb::Management::Profile.all.detect {|p| p.web_property_id == 'UA-XXXXXXX-X'}
 
 Define a Report Class
 ---------------------
 
     class Exits
-      extend Garb::Resource
+      extend Garb::Model
 
-      metrics :exits, :pageviews, :exit_rate
+      metrics :exits, :pageviews
       dimensions :page_path
-      sort :exits
-
-      filters do
-        eql(:page_path, 'season')
-      end
-
-      # alternative:
-      # filters :page_path.eql => 10
     end
 
 Get the Results
 ---------------
 
-    > Exits.results(profile)
+    > Exits.results(profile, :filters => {:page_path.eql => '/'})
 
   OR shorthand
 
-    > profile.exits
+    > profile.exits(:filters => {:page_path.eql => '/'})
+
+  Be forewarned, these numbers are for the last **30** days and may be slightly different from the numbers displayed in Google Analytics' dashboard for **1 month**.
 
 Other Parameters
 ----------------
@@ -88,7 +82,7 @@ Other Parameters
 Metrics & Dimensions
 --------------------
 
-  Metrics and Dimensions are very complex because of the ways in which the can and cannot be combined.
+  **Metrics and Dimensions are very complex because of the ways in which the can and cannot be combined.**
 
   I suggest reading the google documentation to familiarize yourself with this.
 
@@ -97,52 +91,6 @@ Metrics & Dimensions
   When you've returned, you can pass the appropriate combinations (up to 50 metrics and 2 dimenstions)
   to garb, as an array, of symbols. Or you can simply push a symbol into the array.
 
-Sorting
--------
-
-  Sorting can be done on any metric or dimension defined in the request, with .desc reversing the sort.
-
-Building a Report
------------------
-
-  Given the class, session, and profile from above we can do:
-
-    Exits.results(profile, :limit => 10, :offset => 19)
-
-  Or, with sorting and filters:
-
-    Exits.results(profile, :limit => 10, :offset => 19) do
-      sort :exits
-
-      filters do
-        contains(:page_path, 'season')
-        gt(:exits, 100)
-      end
-
-      # or with a hash
-      # filters :page_path.contains => 'season', :exits.gt => 100
-    end
-
-  reports will be an array of OpenStructs with methods for the metrics and dimensions returned.
-
-Build a One-Off Report
-----------------------
-
-    report = Garb::Report.new(profile)
-    report.metrics :pageviews, :exits
-    report.dimensions :page_path
-    report.sort :exits
-
-    report.filters do
-      contains(:page_path, 'season')
-      gte(:exits, 10)
-    and
-
-    # or with a hash
-    # report.filters :page_path.contains => 'season', :exits.gt => 100
-
-    report.results
-
 Filtering
 ---------
 
@@ -174,15 +122,9 @@ Filtering
     substring => '=@',
     not_substring => '!@'
     
-  Given the previous example one-off report, we can add a line for filter:
-  
-    report.filters do
-      eql(:page_path, '/extend/effectively-using-git-with-subversion/')
-    end
-
-  Or, if you're comfortable using symbol operators:
+  Given the previous Exits example report, we can add an options for filter:
 
-    report.filters :page_path.eql => '/extend/effectively-using-git-with-subversion/'
+    profile.exits(:filters => {:page_path.eql => '/extend/effectively-using-git-with-subversion/')
 
 SSL
 ---
@@ -200,9 +142,7 @@ SSL
 TODOS
 -----
 
-  * Read opensearch header in results
-  * Investigate new features from GA to see if they're in the API, implement if so
-  * clarify AND/OR filtering behavior in code and documentation
+  * rebuild AND/OR filtering in Garb::Model
 
 Requirements
 ------------
@@ -213,13 +153,13 @@ Requirements
 Requirements for Testing
 ------------------------
 
+  * shoulda
   * jferris-mocha
-  * tpitale-shoulda (works with minitest)
 
 Install
 -------
 
-    sudo gem install garb
+    gem install garb
 
 Contributors
 ------------

data/lib/garb.rb

@@ -33,9 +33,11 @@ require 'garb/model'
 
 # management
 require 'garb/management/feed'
+require 'garb/management/segment'
 require 'garb/management/account'
 require 'garb/management/web_property'
 require 'garb/management/profile'
+require 'garb/management/goal'
 
 require 'support'
 

data/lib/garb/account.rb

@@ -9,6 +9,7 @@ module Garb
     end
 
     def self.all(session = Session)
+      ActiveSupport::Deprecation.warn("The use of Garb::Account has been deprecated in favor of 'Garb::Management::Account'")
       profiles = {}
 
       Profile.all(session).each do |profile|

data/lib/garb/account_feed_request.rb

@@ -15,11 +15,11 @@ module Garb
     end
 
     def entries
-      parsed_response ? [parsed_response['feed']['entry']].flatten : []
+      parsed_response ? Array(parsed_response['feed']['entry']).flatten.compact : []
     end
 
     def segments
-      parsed_response ? [parsed_response['feed']['dxp:segment']].flatten : []
+      parsed_response ? Array(parsed_response['feed']['dxp:segment']).flatten.compact : []
     end
   end
 end

data/lib/garb/destination.rb

@@ -1,6 +1,8 @@
 module Garb
   class Destination
-    attr_reader :match_type, :expression, :steps
+    attr_reader :match_type, :expression, :steps, :case_sensitive
+
+    alias :case_sensitive? :case_sensitive
 
     def initialize(attributes)
       return unless attributes.is_a?(Hash)
@@ -12,9 +14,5 @@ module Garb
       step_attributes = attributes[Garb.to_ga('step')]
       @steps = Array(step_attributes.is_a?(Hash) ? [step_attributes] : step_attributes).map {|s| Step.new(s)}
     end
-
-    def case_sensitive?
-      @case_sensitive
-    end
   end
 end

data/lib/garb/management/account.rb

@@ -5,8 +5,7 @@ module Garb
       attr_accessor :id, :title, :name
 
       def self.all(session = Session)
-        feed = Feed.new(session, '/accounts') # builds request and parses response
-
+        feed = Feed.new(session, '/accounts')
         feed.entries.map {|entry| new_from_entry(entry, session)}
       end
 
@@ -14,7 +13,7 @@ module Garb
         account = new
         account.session = session
         account.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
-        account.title = entry['title'].gsub('Google Analytics Account ', '')
+        account.title = entry['title'].gsub('Google Analytics Account ', '') # can we get this in properties=?
         account.properties = Garb.parse_properties(entry)
         account
       end
@@ -25,12 +24,16 @@ module Garb
       end
 
       def web_properties
-        @web_properties ||= WebProperty.for_account(self) # will call path
+        @web_properties ||= WebProperty.for_account(self)
       end
 
       def profiles
         @profiles ||= Profile.for_account(self)
       end
+
+      def goals
+        @goals ||= Goal.for_account(self)
+      end
     end
   end
 end

data/lib/garb/management/feed.rb

@@ -15,7 +15,7 @@ module Garb
 
       def entries
         # possible to have nil entries, yuck
-        parsed_response ? [parsed_response['feed']['entry']].flatten.reject {|e| e.nil?} : []
+        parsed_response ? Array(parsed_response['feed']['entry']).flatten.compact : []
       end
 
       def response

data/lib/garb/management/goal.rb

@@ -1,20 +1,44 @@
 module Garb
-  class Goal
-    attr_reader :name, :number, :value, :destination
+  module Management
+    class Goal
 
-    def initialize(attributes={})
-      return unless attributes.is_a?(Hash)
+      attr_accessor :session, :path
+      attr_accessor :name, :number, :value, :destination, :active
 
-      @name = attributes['name']
-      @number = attributes['number'].to_i
-      @value = attributes['value'].to_f
-      @active = (attributes['active'] == 'true')
+      alias :active? :active
 
-      @destination = Destination.new(attributes[Garb.to_ga('destination')])
-    end
+      def self.all(session = Session, path = '/accounts/~all/webproperties/~all/profiles/~all/goals')
+        feed = Feed.new(session, path)
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.for_account(account)
+        all(account.session, account.path + '/webproperties/~all/profiles/~all/goals')
+      end
+
+      def self.for_web_property(web_property)
+        all(web_property.session, web_property.path + '/profiles/~all/goals')
+      end
+
+      def self.for_profile(profile)
+        all(profile.session, profile.path + '/goals')
+      end
+
+      def self.new_from_entry(entry, session)
+        goal = new
+        goal.session = session
+        goal.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        goal.properties = entry[Garb.to_ga('goal')]
+        goal
+      end
 
-    def active?
-      @active
+      def properties=(properties)
+        self.name = properties["name"]
+        self.number = properties["number"].to_i
+        self.value = properties["value"].to_f
+        self.active = (properties["active"] == "true")
+        self.destination = Destination.new(properties[Garb.to_ga('destination')])
+      end
     end
   end
 end

data/lib/garb/management/profile.rb

@@ -22,11 +22,9 @@ module Garb
 
       def self.new_from_entry(entry, session)
         profile = new
-
         profile.session = session
         profile.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
         profile.properties = Garb.parse_properties(entry)
-
         profile
       end
 
@@ -38,8 +36,9 @@ module Garb
         self.web_property_id = properties['web_property_id']
       end
 
-      # def goals
-      # end
+      def goals
+        Goal.for_profile(self)
+      end
     end
   end
 end

data/lib/garb/management/segment.rb

@@ -0,0 +1,27 @@
+module Garb
+  module Management
+    class Segment
+      attr_accessor :session, :path
+      attr_accessor :id, :name, :definition
+
+      def self.all(session = Session)
+        feed = Feed.new(session, '/segments')
+        feed.entries.map {|entry| new_from_entry(entry, session)}
+      end
+
+      def self.new_from_entry(entry, session)
+        segment = new
+        segment.session = session
+        segment.path = Garb.parse_link(entry, "self").gsub(Feed::BASE_URL, '')
+        segment.properties = entry['dxp:segment']
+        segment
+      end
+
+      def properties=(properties)
+        self.id = properties['id']
+        self.name = properties['name']
+        self.definition = properties['dxp:definition']
+      end
+    end
+  end
+end

data/lib/garb/management/web_property.rb

@@ -29,6 +29,10 @@ module Garb
       def profiles
         @profiles ||= Profile.for_web_property(self)
       end
+
+      def goals
+        @goals ||= Goal.for_web_property(self)
+      end
     end
   end
 end

data/lib/garb/resource.rb

@@ -10,7 +10,7 @@ module Garb
       # returns Exits.results(self, options_hash, &block)
       # every class defined which extends Resource will add to the module
 
-      # ActiveSupport::Deprecation.warn
+      ActiveSupport::Deprecation.warn("The use of Garb::Resource will be removed in favor of 'extend Garb::Model'")
       ProfileReports.add_report_method(base)
     end
 

data/lib/garb/version.rb

@@ -2,8 +2,8 @@ module Garb
   module Version
 
     MAJOR = 0
-    MINOR = 8
-    TINY  = 5
+    MINOR = 9
+    TINY  = 0
 
     def self.to_s # :nodoc:
       [MAJOR, MINOR, TINY].join('.')

data/test/test_helper.rb

@@ -1,6 +1,14 @@
 begin
   require 'simplecov'
-  SimpleCov.start 'rails'
+  SimpleCov.adapters.define 'garb' do
+    add_filter '/test/'
+    add_filter '/config/'
+    add_filter 'version'
+
+    add_group 'Libraries', 'lib'
+  end
+
+  SimpleCov.start 'garb'
 rescue LoadError
   puts "Install simplecov if you use 1.9 and want coverage metrics"
 end