xeroizer-float 2.15.3.1

data/lib/xeroizer/record/base_model.rb

@@ -0,0 +1,144 @@
+require 'xeroizer/record/base_model_http_proxy'
+
+module Xeroizer
+  module Record
+    
+    class BaseModel
+
+      include ClassLevelInheritableAttributes
+      class_inheritable_attributes :api_controller_name
+      
+      class InvaidPermissionError < StandardError; end
+      ALLOWED_PERMISSIONS = [:read, :write, :update]
+      class_inheritable_attributes :permissions
+      
+      class_inheritable_attributes :xml_root_name
+      class_inheritable_attributes :optional_xml_root_name
+      class_inheritable_attributes :xml_node_name
+      
+      include BaseModelHttpProxy
+
+      attr_reader :application
+      attr_reader :model_name
+      attr :model_class
+      attr_reader :response
+      
+      class << self
+        
+        # Method to allow override of the default controller name used 
+        # in the API URLs. 
+        #
+        # Default: pluaralized model name (e.g. if the controller name is
+        # Invoice then the default is Invoices.
+        def set_api_controller_name(controller_name)
+          self.api_controller_name = controller_name
+        end
+        
+        # Set the permissions allowed for this class type.
+        # There are no permissions set by default.
+        # Valid permissions are :read, :write, :update.
+        def set_permissions(*args)
+          self.permissions = {}
+          args.each do | permission |
+            raise InvaidPermissionError.new("Permission #{permission} is invalid.") unless ALLOWED_PERMISSIONS.include?(permission)
+            self.permissions[permission] = true
+          end
+        end
+        
+        # Method to allow override of the default XML node name.
+        #
+        # Default: singularized model name in camel-case.
+        def set_xml_node_name(node_name)
+          self.xml_node_name = node_name
+        end
+        
+        # Method to allow override of the default XML root name to use
+        # in has_many associations.
+        def set_xml_root_name(root_name)
+          self.xml_root_name = root_name
+        end
+        
+        # Method to add an extra top-level node to use in has_many associations.
+        def set_optional_xml_root_name(optional_root_name)
+          self.optional_root_name = optional_root_name
+        end
+        
+      end
+            
+      public
+        
+        def initialize(application, model_name)
+          @application = application
+          @model_name = model_name
+        end
+        
+        # Retrieve the controller name.
+        #
+        # Default: pluaralized model name (e.g. if the controller name is
+        # Invoice then the default is Invoices.
+        def api_controller_name
+          self.class.api_controller_name || model_name.pluralize
+        end
+        
+        def model_class
+          @model_class ||= Xeroizer::Record.const_get(model_name.to_sym)
+        end
+        
+        # Build a record with attributes set to the value of attributes.
+        def build(attributes = {})
+          model_class.build(attributes, self)
+        end
+
+        # Create (build and save) a record with attributes set to the value of attributes.
+        def create(attributes = {})
+          build(attributes).tap { |resource| resource.save }
+        end
+        
+        # Retreive full record list for this model. 
+        def all(options = {})
+          raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+          response_xml = http_get(parse_params(options))
+          response = parse_response(response_xml, options)
+          response.response_items || []
+        end
+        
+        # Helper method to retrieve just the first element from
+        # the full record list.
+        def first(options = {})
+          raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+          result = all(options)
+          result.first if result.is_a?(Array)
+        end
+        
+        # Retrieve record matching the passed in ID.
+        def find(id, options = {})
+          raise MethodNotAllowed.new(self, :all) unless self.class.permissions[:read]
+          response_xml = @application.http_get(@application.client, "#{url}/#{CGI.escape(id)}", options)
+          response = parse_response(response_xml, options)
+          result = response.response_items.first if response.response_items.is_a?(Array)
+          result.complete_record_downloaded = true if result
+          result
+        end
+        
+        def parse_response(response_xml, options = {})
+          Response.parse(response_xml, options) do | response, elements, response_model_name |
+            if model_name == response_model_name
+              @response = response
+              parse_records(response, elements)
+            end
+          end
+        end
+                
+      protected
+        
+        # Parse the records part of the XML response and builds model instances as necessary.
+        def parse_records(response, elements)
+          elements.each do | element |
+            response.response_items << model_class.build_from_node(element, self)
+          end
+        end
+        
+    end
+    
+  end
+end

data/lib/xeroizer/record/base_model_http_proxy.rb

@@ -0,0 +1,117 @@
+require 'xeroizer/application_http_proxy' 
+
+module Xeroizer
+  module Record
+    module BaseModelHttpProxy
+      
+      def self.included(base)
+        base.send :include, Xeroizer::ApplicationHttpProxy
+        base.send :include, InstanceMethods
+      end
+      
+      module InstanceMethods
+        
+        protected
+        
+          # Parse parameters for GET requests.
+          def parse_params(options)
+            params = {}
+            params[:ModifiedAfter]  = options[:modified_since] if options[:modified_since]          
+            params[:OrderBy]        = options[:order] if options[:order]
+            if options[:where]
+              params[:where] =  case options[:where]
+                                  when String   then options[:where] 
+                                  when Hash     then parse_where_hash(options[:where])
+                                end
+            end
+            params[:offset] = options[:offset] if options[:offset]
+            params
+          end
+        
+          # Parse the :where part of the options for GET parameters and construct a valid
+          # .Net version of the criteria to pass to Xero.
+          #
+          # Attribute names can be modified as follows to change the expression used:
+          #   {attribute_name}_is_greater_than or {attribute_name}> uses '>'
+          #   {attribute_name}_is_greater_than_or_equal_to or {attribute_name}>= uses '>='
+          #   {attribute_name}_is_less_than or {attribute_name}< uses '<'
+          #   {attribute_name}_is_less_than_or_equal_to or {attribute_name}< uses '<='
+          #   DEFAULT: '=='
+          def parse_where_hash(where)
+            conditions = []
+            where.each do | key, value |
+              (attribute_name, expression) = extract_expression_from_attribute_name(key)
+              (field_name, field) = model_class.fields.find { | k, v | v[:internal_name] == attribute_name }
+              if field
+                conditions << where_condition_part(field, expression, value)                
+              else
+                raise InvalidAttributeInWhere.new(model_name, attribute_name)
+              end
+            end
+            conditions.map { | (attr, expression, value) | "#{attr}#{expression}#{value}"}.join('&&')
+          end
+        
+          # Extract the attribute name and expression from the attribute.
+          #
+          # @return [Array] containing [actual_attribute_name, expression]
+          def extract_expression_from_attribute_name(key)
+            case key.to_s
+              when /(_is_not|\<\>)$/
+                [
+                  key.to_s.gsub(/(_is_not|\<\>)$/, '').to_sym,
+                  '<>'
+                ]
+              
+              when /(_is_greater_than|\>)$/
+                [
+                  key.to_s.gsub(/(_is_greater_than|\>)$/, '').to_sym,
+                  '>'
+                ]
+              
+              when /(_is_greater_than_or_equal_to|\>\=)$/
+                [
+                  key.to_s.gsub(/(_is_greater_than_or_equal_to|\>\=)$/, '').to_sym,
+                  '>='
+                ]
+              
+              when /(_is_less_than|\<)$/
+                [
+                  key.to_s.gsub(/(_is_less_than|\<)$/, '').to_sym,
+                  '<'
+                ]
+              
+              when /(_is_less_than_or_equal_to|\<\=)$/
+                [
+                  key.to_s.gsub(/(_is_less_than_or_equal_to|\<\=)$/, '').to_sym,
+                  '<='
+                ]
+                              
+              else
+                [key, '==']
+              
+            end
+          end
+        
+          # Creates a condition part array containing the:
+          #   * Field's API name
+          #   * Expression
+          #   * .Net formatted value.
+          def where_condition_part(field, expression, value)
+            case field[:type]
+              when :guid        then ["#{field[:api_name]}.ToString()", expression, "\"#{value}\""]
+              when :string      then [field[:api_name], expression, "\"#{value}\""]
+              when :boolean     then [field[:api_name], expression, value ? 'true' : 'false']
+              when :integer     then [field[:api_name], expression, value.to_s]
+              when :decimal     then [field[:api_name], expression, value.to_s]
+              when :date        then [field[:api_name], expression, "DateTime.Parse(\"#{value.strftime("%Y-%m-%d")}\")"]
+              when :datetime    then [field[:api_name], expression, "DateTime.Parse(\"#{value.utc.strftime("%Y-%m-%dT%H:%M:%S")}\")"]
+              when :belongs_to  then
+              when :has_many    then
+            end
+          end
+
+      end
+    
+    end
+  end
+end

data/lib/xeroizer/record/model_definition_helper.rb

@@ -0,0 +1,99 @@
+module Xeroizer
+  module Record
+    module ModelDefinitionHelper
+      
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.send :include, InstanceMethods
+      end
+      
+      module ClassMethods
+
+        # Possible primary keys. At least one of these must exist before attempting to update a record.
+        def set_possible_primary_keys(*args)
+          args = [args] unless args.is_a?(Array)
+          self.possible_primary_keys = args
+        end
+        
+        # Set the actual Xero primary key for this record.
+        def set_primary_key(primary_key_name)
+          self.primary_key_name = primary_key_name
+        end
+        
+        # Whether this record type's list results contain summary data only.
+        #
+        # Records like invoices, when returning a list, only show summary data for
+        # certain types of associations (like the contact record) and do not return
+        # any data for line items.
+        #
+        # Default: false
+        def list_contains_summary_only(status)
+          self.summary_only = status
+        end
+        
+        def list_contains_summary_only?
+          !!summary_only
+        end
+              
+        # Helper methods used to define the fields this model has.
+        def string(field_name, options = {});     define_simple_attribute(field_name, :string, options); end
+        def boolean(field_name, options = {});    define_simple_attribute(field_name, :boolean, options); end
+        def integer(field_name, options = {});    define_simple_attribute(field_name, :integer, options, 0); end
+        def decimal(field_name, options = {});    define_simple_attribute(field_name, :decimal, options, 0.0); end
+        def date(field_name, options = {});       define_simple_attribute(field_name, :date, options); end
+        def datetime(field_name, options = {});   define_simple_attribute(field_name, :datetime, options); end
+        def datetime_utc(field_name, options = {});   define_simple_attribute(field_name, :datetime_utc, options); end
+        
+        def guid(field_name, options = {})
+          # Ensure all automated Id conversions are changed to ID.
+          options[:api_name] ||= field_name.to_s.camelize.gsub(/Id/, 'ID')
+          define_simple_attribute(field_name, :guid, options)
+        end
+              
+        # Helper method to simplify field definition. 
+        # Creates an accessor and reader for the field.
+        # Options:
+        #   :internal_name => allows the specification of an internal field name differing from the API's field name.
+        #   :api_name => allows the API name to be specified if it can't be properly converted from camelize.
+        #   :model_name => allows class used for children to be different from it's ndoe name in the XML.
+        #   :type => type of field
+        #   :skip_writer => skip the writer method
+        def define_simple_attribute(field_name, field_type, options, value_if_nil = nil)
+          self.fields ||= {}
+          
+          internal_field_name = options[:internal_name] || field_name
+          self.fields[field_name] = options.merge({
+            :internal_name  => internal_field_name, 
+            :api_name       => options[:api_name] || field_name.to_s.camelize,
+            :type           => field_type
+          })
+          define_method internal_field_name do 
+            @attributes[field_name] || value_if_nil
+          end
+          
+          unless options[:skip_writer]
+            define_method "#{internal_field_name}=".to_sym do | value | 
+              @attributes[field_name] = value
+            end
+          end
+        end
+        
+      end
+      
+      module InstanceMethods
+        
+        # Returns the value of the Xero primary key for this record if it exists.
+        def id
+          self[self.class.primary_key_name]
+        end
+
+        # Sets the value of the Xero primary key for this record if it exists.
+        def id=(new_id)
+          self[self.class.primary_key_name] = new_id
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/xeroizer/record/record_association_helper.rb

@@ -0,0 +1,140 @@
+module Xeroizer
+  module Record
+    module RecordAssociationHelper
+      
+      def self.included(base)
+        base.extend(ClassMethods)    
+      end
+      
+      module ClassMethods
+        
+        def belongs_to(field_name, options = {})
+          internal_field_name = options[:internal_name] || field_name
+          internal_singular_field_name = internal_field_name.to_s.singularize
+          
+          define_association_attribute(field_name, internal_singular_field_name, :belongs_to, options)
+        
+          # Create a #build_record_name method to build the record.
+          define_method "build_#{internal_singular_field_name}" do | *args |
+            attributes = args.size == 1 ? args.first : {}
+          
+            # The name of the record model.
+            model_name = options[:model_name] ? options[:model_name].to_sym : field_name.to_s.singularize.camelize.to_sym
+          
+            # The record's parent instance for this current application.
+            model_parent = new_model_class(model_name)
+          
+            # Create a new record, binding it to it's parent instance.
+            record = Xeroizer::Record.const_get(model_name).build(attributes, model_parent)
+            self.attributes[field_name] = record
+          end
+        end
+      
+        def has_many(field_name, options = {})
+          internal_field_name = options[:internal_name] || field_name
+          internal_singular_field_name = internal_field_name.to_s.singularize
+        
+          define_association_attribute(field_name, internal_field_name, :has_many, options)
+                  
+          # Create an #add_record_name method to build the record and add to the attributes.
+          define_method "add_#{internal_singular_field_name}" do | *args |
+            # The name of the record model.
+            model_name = options[:model_name] ? options[:model_name].to_sym : field_name.to_s.singularize.camelize.to_sym
+
+            # The record's parent instance for this current application.
+            model_parent = new_model_class(model_name)
+          
+            # The class of this record.
+            record_class = Xeroizer::Record.const_get(model_name)
+
+            # Parse the *args variable so that we can use this method like:
+            #   add_record({fields}, {fields}, ...)
+            #   add_record(record_one, record_two, ...)
+            #   add_record([{fields}, {fields}], ...)
+            #   add_record(key => val, key2 => val)
+            records = []
+            if args.size == 1 && args.first.is_a?(Array)
+              records = args.first
+            elsif args.size > 0 
+              records = args
+            else
+              raise StandardError.new("Invalid arguments for #{self.class.name}#add_#{internal_singular_field_name}(#{args.inspect}).")
+            end
+          
+            # Ensure that complete record is downloaded before adding new records
+            self.send(field_name)
+            
+            # Add each record.
+            last_record = nil
+            records.each do | record |
+              record = record_class.build(record, model_parent) if record.is_a?(Hash)
+              raise StandardError.new("Record #{record.class.name} is not a #{record_class.name}.") unless record.is_a?(record_class)
+              self.attributes[field_name] ||= []
+              self.attributes[field_name] << record
+              last_record = record
+            end
+            
+            last_record # last record
+          end
+          
+        end
+        
+        def define_association_attribute(field_name, internal_field_name, association_type, options)
+          define_simple_attribute(field_name, association_type, options.merge!(:skip_writer => true), ((association_type == :has_many) ? [] : nil))
+          
+          internal_field_name = options[:internal_name] || field_name
+          internal_singular_field_name = internal_field_name.to_s.singularize
+          model_name = options[:model_name] ? options[:model_name].to_sym : field_name.to_s.singularize.camelize.to_sym
+    
+          define_method "#{internal_field_name}=".to_sym do | value | 
+            record_class = Xeroizer::Record.const_get(model_name)
+            case value
+              when Hash 
+                self.attributes[field_name] = ((association_type == :has_many) ? [] : nil)
+                case association_type
+                  when :has_many  
+                    self.attributes[field_name] = []
+                    self.send("add_#{internal_singular_field_name}".to_sym, value)
+                    
+                  when :belongs_to  
+                    self.attributes[field_name] = Xeroizer::Record.const_get(model_name).build(value, new_model_class(model_name))
+                    
+                end
+                
+              when Array
+                self.attributes[field_name] = ((association_type == :has_many) ? [] : nil)
+                value.each do | single_value |
+                  case single_value
+                    when Hash         then send("add_#{internal_singular_field_name}".to_sym, single_value)
+                    when record_class then self.attributes[field_name] << single_value
+                    else                   raise AssociationTypeMismatch.new(record_class, single_value.class)
+                  end
+                end
+                
+              when record_class
+                self.attributes[field_name] = ((association_type == :has_many) ? [value] : value)
+                
+              when NilClass
+                self.attributes[field_name] = []
+                
+              else
+                raise AssociationTypeMismatch.new(record_class, value.class)
+            end
+          end
+          
+          # Override reader for this association if this association belongs
+          # to a summary-typed record. This will automatically attempt to download
+          # the complete version of the record before accessing the association.
+          if list_contains_summary_only?
+            define_method internal_field_name do
+              download_complete_record! unless new_record? || options[:list_complete] || complete_record_downloaded?
+              self.attributes[field_name] || ((association_type == :has_many) ? [] : nil)
+            end
+          end
+        end
+        
+      end
+      
+    end
+  end
+end