mirror_mirror 0.0.2 → 0.0.3

data/README.md

@@ -65,6 +65,6 @@ In this scenario a `contractor_id` is present, but we don't know if the `Contrac
     <h1>Today's Punched-In Contractors</h1>
     <ul>
       <% @timesheets.each do |timesheet| %>
-        <li><%= "#{timesheet.worker.first_name} #{timesheet.worker.last_name}"</li>
+        <li><%= "#{timesheet.contractor.first_name} #{timesheet.contractor.last_name}"</li>
       <% end %>
     </ul>

data/lib/mirror_mirror/active_record_base.rb

@@ -4,15 +4,20 @@ module MirrorMirror::ActiveRecordBase
   included do
     
     def reflect!
+      reflect
+      save!
+      self
+    end
+
+    def reflect
       hash = self.class.mirror_request!(:get, mirror_url)
       raise RecordNotFound, "Non-Hash returned from resource: #{mirror_url} => #{hash.inspect}" unless hash.is_a?(Hash)
       raise RecordNotFound, "Empty hash returned from resource."  unless hash.any?
       hash.each {|k,v| send("#{k}=", v) if respond_to?("#{k}=") }
-      self.updated_at = Time.now
-      save!
       self
     end
 
+    # (See #mirror_url)
     def mirror_url
       self.class.mirror_url(id)
     end
@@ -21,32 +26,65 @@ module MirrorMirror::ActiveRecordBase
 
   module ClassMethods
     
+    # The setup/configuration method for mirror_mirror functionality.
+    # @param [String] url the url of the resource collection (e.g., http://example.com/api/books)
+    # @param [Hash] options
+    #   * :find (Boolean) (default to: false) - If true, `#find` will automatically attempt to `#reflect!` the external record based on the given id.
+    #   * :request (Symbol, Nil) (defaults to: nil) - Specify a custom class method within the model which will perform the HTTP request.
+    # @return [Nil]
     def mirror_mirror(*args)
       options = args.extract_options!
       raise ArgumentError, "url is blank." if args[0].blank?
       options[:url]           = args[0]
       @mirror_mirrior_options = options
+      nil
     end
 
+    # Determine if this class has been setup to mirror an external resource using `MirrorMirror`.
+    # 
+    # @return [Boolean]
     def mirroring?
-      @mirror_mirrior_options.present?
+      mirror_mirror_options[:url].present?
     end
 
-    def mirror_mirror_options(option)
+    # Get one, or all, of the mirror_mirror class options. 
+    # 
+    # @param [Symbol] option the specific option key (e.g., :find, :url, :request)
+    # @return [Mixed, Hash] mixed option values, or a Hash containg all class options.
+    def mirror_mirror_options(option = nil)
       @mirror_mirrior_options ||= {}
-      @mirror_mirrior_options[option]
+      if option.nil?
+        @mirror_mirrior_options
+      else
+        @mirror_mirrior_options[option]
+      end
     end
 
+    # Determine if the `:find => true` option has been specified for this class.
+    # 
+    # @return [Boolean]
     def mirror_find?
       mirroring? ? @mirror_mirrior_options[:find] : false
     end
 
+    # Get the url specified in the Model's `#mirror_mirror` setup. Optionally specify a record `id`.
+    # 
+    # @param [Integer] id the resource record id.
+    # @return [String] the url.
     def mirror_url(id = nil)
       url = @mirror_mirrior_options[:url]
       url += "/#{id.to_i}" if id.to_i > 0
       url
     end
 
+    # A universial `request` method, used internally, that maps to either the default `#MirrorMirror.request!` method, or
+    # to a the optional `:request` method specified in the #mirror_mirror options of the Model. 
+    # 
+    # @note Will probably go through sweeping changes in the near future.
+    # @param [Symbol] verb the http request verb. (`:get`, `:put`, `:post`, and `:delete` are supported)
+    # @param [String] url the url to be requested.
+    # @param [Hash] params the parameters sent along with the request.
+    # @return [Hash, Array] dependant on the context of the call (Record vs Collection)
     def mirror_request!(verb, url, params = {})
       method = @mirror_mirrior_options[:request]
       if method.present?
@@ -65,6 +103,11 @@ module MirrorMirror::ActiveRecordBase
       end
     end
 
+    # Attempt to reflect all items from the external collection.
+    # 
+    # @note Not ready for usage; just a thought worth building off from. 
+    # @param [Hash] params the parameters to be passed to the request method.
+    # @return [Array] of active record objects.
     def reflect_all!(params = {})
       array = mirror_request(:get, mirror_url, params)
       raise RecordNotFound, "Non-Array returned from resource: #{mirror_url} => #{hash.inspect}" unless array.is_a?(Array)
@@ -83,20 +126,10 @@ module MirrorMirror::ActiveRecordBase
       all
     end
 
-    # Active Record Polymorphing
-    def find(*args)
-      return super unless mirror_find?
-      begin
-        super
-      rescue ActiveRecord::RecordNotFound
-        if (id = args[0].to_i) > 0
-          record    = self.new
-          record.id = id
-          record.reflect!
-        end
-      end
-    end
-
+    # Initialize a new record, set the id, and call `#reflect!`
+    #
+    # @param [Integer] id the id of the record.
+    # @return [Object] the active record object.
     def reflect_by_id!(id)
       record = self.new
       record.id = id
@@ -104,12 +137,32 @@ module MirrorMirror::ActiveRecordBase
       record
     end
 
+    # Call to find_or_initialize_by_id, and `#reflect!` if the record was not found locally.
+    #
+    # @param [Integer] id the id of the record.
+    # @return [Object] the active record object.
     def find_or_reflect_by_id!(*args)
       record = find_or_initialize_by_id(*args)
       record.reflect! if record.new_record?
       record
     end
 
+    # Monkey-Patching of the `ActiveRecord::Base.find()` method to support the `:find => true` option (see #mirror_mirror)
+    def find(*args)
+      return super unless mirror_find?
+      begin
+        super
+      rescue ActiveRecord::RecordNotFound
+        if (id = args[0].to_i) > 0
+          record    = self.new
+          record.id = id
+          record.reflect!
+        end
+      end
+    end
+    
+    # Monkey-Patching of the `ActiveRecord::Base.belongs_to()` method to support an extra option `:auto_reflect => true`
+    # which allows for automatic retrival of the associated record based on the `:foreign_key` using `#find()`
     def belongs_to(*args)
       options           = args.extract_options!
       association_name  = args[0].to_s

data/lib/mirror_mirror/version.rb

@@ -1,3 +1,3 @@
 module MirrorMirror
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -2,7 +2,7 @@
 name: mirror_mirror
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Daniel Doezema
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-06-17 00:00:00 Z
+date: 2012-06-19 00:00:00 Z
 dependencies: []
 
 description: Allows for easier interactions and integration with external REST resources.
@@ -62,3 +62,4 @@ specification_version: 3
 summary: Allows for easier interactions and integration with external REST resources.
 test_files: []
 
+has_rdoc: