gdata_spreadsheet 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,9 +1,101 @@
 = GData Spreadsheet
 
+Use the GData API the way its meant to be: OO-style!
+
+
+== Installation
+
+  gem install gdata_spreadsheet
+
+
+== Setup
+
+You have to initialise the connection by setting up the config:
+
+  Google::Config.file = File.join(File.dirname(__FILE__), "google.yml")
+
+The config file itself looks like this:
+
+  account:          account@google.com
+  worksheet_token:  session_token_for_worksheets
+  list_token:       session_token_for_lists
+
+Don't know how to get session tokens? Check this out: http://blog.tricycledevelopments.com/2010/08/19/gdata-authsub.html
+
+
+== Usage
+
+Just create a subclass of the <tt>Google::Base</tt> class and overwrite <tt>worksheet_name, id_column and sync_attributes</tt>.
+A very simple example is the <tt>Log</tt> class, which can be used to write messages to a spreadsheet.
+A more advanced example would be this:
+
+  module Google
+    class Order < Google::Base
+      attr_reader :line_items
+
+      def initialize(doc_id, id = nil, items = [])
+        super doc_id, id
+
+        @line_items = items
+      end
+
+      def id_column
+        "ordernumber"
+      end
+
+      def worksheet_name
+        "orders"
+      end
+
+      def sync_attributes
+        {
+          :timestamp        => Time.now.strftime("%d/%m/%Y %H:%M"),
+          :ordernumber      => 123,
+          ...
+          :lineitems        => line_items,
+          ...
+        }
+      end
+    end
+  end
+
+
+== Finding / updating existing records
+
+The second parameter for the <tt>Base</tt> initialiser takes an ID. If an ID value is provided (and the <tt>id_column</tt> is specified),
+then the matching row will be fetched from the spreadsheet while mapping all existing attributes (see 'How do attributes map?' for more information).
+
+  order = Google::Order.new("spreadsheet_id", "1234")
+
+The record can then be written to the spreadsheet by calling <tt>save</tt>. If <tt>sync!</tt> is executed,
+the attributes will be updated according to the mapping specified in <tt>sync_attributes</tt>.
+
+  order.save
+
+
+== Creating new records
+
+Just instantiate your model without an ID. <tt>sync!</tt> will take care of pushing the data to the spreadsheet.
+
+  order = Google::Order.new("spreadsheet_id")
+  order.sync!
+
+
+== How do attributes map?
+
+All attributes can then be accessed using the regular getters and setters:
+
+  order = Google::Order.new("spreadsheet_id")
+  order.ordernumber = "4321"
+  order.ordernumber             # => "4321"
+
+Google uses a shortened version of the column headers and strips all characters except for <tt>[a-z0-9]</tt>.
+So when your column header in the spreadsheet reads 'Order Number', the mapped attribute in your code will be 'ordernumber'.
+Make sure to call the correct methods!
 
 
 == Note on Patches/Pull Requests
- 
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/gdata_spreadsheet.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{gdata_spreadsheet}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tom"]
-  s.date = %q{2010-08-30}
+  s.date = %q{2010-09-01}
   s.description = %q{}
   s.email = %q{tom@trike.com.au}
   s.extra_rdoc_files = [

data/lib/google/base.rb

@@ -1,7 +1,26 @@
 module Google
+
+  # Base class for all your spreadsheet models.
+  # Check the Readme for detailed information on how it's used.
+  #
+  # === Finding / updating existing records
+  #
+  #   order = Google::Order.new("spreadsheet_id", "1234")
+  #   order.save
+  #
+  # === Creating new records
+  #
+  #   order = Google::Order.new("spreadsheet_id")
+  #   order.sync!
   class Base
     attr_reader :doc
 
+    # The standard initialiser takes the spreadsheet ID and an optional record ID
+    # (check the Readme to see how records are mapped). Overwrite the initialiser
+    # in order to pass in other necessary information (eg. as in Log).
+    #
+    # If a record ID is specified, then the associated row from the spreadsheet will be fetched,
+    # otherwise a new record is build.
     def initialize(doc_id, row_id = nil)
       raise Google::MissingDocumentError unless doc_id
 
@@ -11,26 +30,7 @@ module Google
       initialize_row row_id
     end
 
-    def initialize_row(id)
-      if id_column && id && @doc = @sheet.row_data(id_column, id.downcase, @worksheet_id)
-        initialize_doc
-      else
-        new_row
-      end
-    end
-
-    def new_row
-      @doc = Nokogiri::XML.parse("<entry xmlns=\"http://www.w3.org/2005/Atom\"></entry>").css("entry").first
-      @doc.add_namespace_definition "gsx", "http://schemas.google.com/spreadsheets/2006/extended"
-      @doc.add_namespace_definition "gd", "http://schemas.google.com/g/2005"
-    end
-
-    def initialize_doc
-      @doc["xmlns"] = "http://www.w3.org/2005/Atom"
-      @doc["xmlns:gsx"] = "http://schemas.google.com/spreadsheets/2006/extended"
-      @doc["xmlns:gd"] = "http://schemas.google.com/g/2005"
-    end
-
+    # Creates or updates the record.
     def save
       if new_record?
         @sheet.add_row @doc, @worksheet_id
@@ -39,34 +39,58 @@ module Google
       end
     end
 
+    # Returns true if the record is not yet pushed to the spreadsheet.
     def new_record?
       !@doc.css("id").first
     end
 
+    # Name of the worksheet that's mapped to the model.
+    #
+    # Overwrite this in your sub-class!
     def worksheet_name
       raise "Abstract! Overwrite this method in your subclass"
     end
 
+    # Name of the column that'll will be used as the ID column.
+    #
+    # Overwrite this in your sub-class!
+    #
+    # <tt>return nil</tt> in your subclass, if you want a push only model
     def id_column
       raise "Abstract! Overwrite this method in your subclass"
-      # return nil in your subclass, if you want a push only model
     end
 
+    # specify how attributes are mapped to the spreadsheet.
+    #
+    # ==== Example
+    #   {
+    #     :timestamp  => Time.now.to_s(:db),
+    #     :message    => @message
+    #   }
+    #
+    # The keys in the hash represent columns in the spreadsheet
+    # (check out the Readme, for more information about attribute mapping), the values will
+    # be written to the cells.
     def sync_attributes
       { }
     end
 
+    # Maps all attributes specified in Base#sync_attributes, so that a subsequent Base#save
+    # will push the data to the spreadsheet columns.
     def sync
       sync_attributes.each do |field, value|
         set field, value
       end
     end
 
+    # Convenience method with executes Base#sync and then Base#save.
     def sync!
       sync
       save
     end
 
+  protected
+
     def method_missing(method, *args, &block)
       method = method.to_s
 
@@ -81,6 +105,26 @@ module Google
 
   private
 
+    def initialize_row(id)
+      if id_column && id && @doc = @sheet.row_data(id_column, id.downcase, @worksheet_id)
+        initialize_doc
+      else
+        new_row
+      end
+    end
+
+    def new_row
+      @doc = Nokogiri::XML.parse("<entry xmlns=\"http://www.w3.org/2005/Atom\"></entry>").css("entry").first
+      @doc.add_namespace_definition "gsx", "http://schemas.google.com/spreadsheets/2006/extended"
+      @doc.add_namespace_definition "gd", "http://schemas.google.com/g/2005"
+    end
+
+    def initialize_doc
+      @doc["xmlns"] = "http://www.w3.org/2005/Atom"
+      @doc["xmlns:gsx"] = "http://schemas.google.com/spreadsheets/2006/extended"
+      @doc["xmlns:gd"] = "http://schemas.google.com/g/2005"
+    end
+
     def attribute(field)
       @doc.xpath(".//gsx:#{field}").first
     end

data/lib/google/config.rb

@@ -1,6 +1,20 @@
 require 'yaml'
 
 module Google
+
+  # Wrapper to access settings.
+  # Unless you specify additional settings in your config file,
+  # you should never have to call settings on your own!
+  #
+  # === Initialisation
+  #
+  #   Google::Config.file = File.join(File.dirname(__FILE__), "google.yml")
+  #
+  # === Example
+  #
+  #   account:          account@google.com
+  #   worksheet_token:  session_token_for_worksheets
+  #   list_token:       session_token_for_lists
   class Config
     def self.file=(path)
       @@file = path

data/lib/google/log.rb

@@ -1,4 +1,13 @@
 module Google
+
+  # Example spreadsheet model.
+  #
+  # This enables very basic message pushing to a spreadsheet named 'sync log'
+  #
+  # === Usage
+  #
+  #   entry = Google::Log.new("spreadsheet_id", "awesome stuff!")
+  #   entry.sync!
   class Log < Base
 
     def initialize(doc_id, message)
@@ -7,6 +16,8 @@ module Google
       @message = message
     end
 
+  private
+
     def worksheet_name
       "sync log"
     end

data/lib/google/spreadsheet.rb

@@ -10,6 +10,9 @@ module Google
   class FatalError < ::Exception
   end
 
+  # Interface to the GData API.
+  #
+  # You shouldn't have to use this class in your code, except when debugging!
   class Spreadsheet
 
     def initialize(key)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: gdata_spreadsheet
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Tom
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-30 00:00:00 +10:00
+date: 2010-09-01 00:00:00 +10:00
 default_executable: 
 dependencies: []