infopark_crm_connector 0.9.2 → 1.0.0

data/lib/crm_connector/core/continuation_support.rb

@@ -1,5 +1,6 @@
-# :stopdoc:
 module Infopark; module Crm; module Core
+
+  # @private
   module ContinuationSupport
     def self.included(klass)
       klass.extend(ClassMethods)

data/lib/crm_connector/core/enumerator.rb

@@ -1,42 +1,51 @@
 require 'backports'
 
 module Infopark; module Crm; module Core
-  # Transparent wrapper for the web service's continuation ability
+  # Transparent wrapper for the web services continuation ability
   class Enumerator < Enumerator
-    def initialize(collection, continuation_handle, size, &block) #:nodoc:
+
+    # @private
+    def initialize(collection, continuation_handle, size, &block)
       update(collection, continuation_handle, size)
       super &block
     end
 
+    ##
     # The +continuation_handle+ parameter to be passed to the next find or search request for
-    # programmatic paging
+    # programmatic paging.
+    # @return [String]
+    # @private
     def continuation_handle
       @continuation_handle
     end
 
-    # The results of the last response as an array,
-    # the array's size is less than or equal to the +limit+ parameter value
+    ##
+    # The results of the last response as an array.
+    # The size of the array is less than or equal to the +limit+ parameter value.
+    # @return [Array]
     def within_limit
       @collection
     end
 
     ##
-    # :method: size
+    # @!method size
     # The total count given by the last search response, if available.
-    # #size is undefined otherwise.
+    # If not available this method is undefiend.
+    # @return [Integer] The total count given by the last search response, if available.
     ##
 
-    #--
+    ##
     # Note: We don't want size to return nil for compatibility for count's behavior
-    #++
-    def update(collection, continuation_handle, size) # :nodoc:
+    # @private
+    def update(collection, continuation_handle, size)
       @collection = collection
       @continuation_handle = continuation_handle
       @size = size
       define_singleton_method(:size) {@size} if @size
     end
 
-    def inspect #:nodoc:
+    # @private
+    def inspect
       "#{super.chop}, @within_limit=#{within_limit.inspect}" +
           ", @continuation_handle=#{continuation_handle.inspect}>"
     end

data/lib/crm_connector/core/known_attributes.rb

@@ -1,8 +1,10 @@
-# :stopdoc:
 module Infopark; module Crm; module Core
+
+  # @private
   class KnownAttributes < Array
     def include?(val)
       val.start_with?('custom_') || super(val)
     end
   end
+
 end; end; end

data/lib/crm_connector/core/resource.rb

@@ -1,18 +1,37 @@
-# :stopdoc:
-require 'ostruct'
+require 'active_support/core_ext/class/attribute_accessors'
 
 module Infopark; module Crm; module Core
-  class Resource < Infopark::Crm::Base
-    include Core::ContinuationSupport
-    include Core::SearchSupport
+  ##
+  # Base class for every resource model
+  #
+  # Supports the ActiveResource::Base lifecycle methods, such as
+  # * Resource.create(attributes)
+  # * Resource.new(attributes)
+  # * Resource.find(id)
+  # * resource.update_attributes(attributes)
+  # * resource.save
+  #
+  # See the {http://rubydoc.info/gems/activeresource/3.2.8/frames ActiveResource documentation} for a detailed description.
+  class Resource < ActiveResource::Base
+    include ContinuationSupport
+    include SearchSupport
 
-    def self.site
-      Infopark::Crm::Base.site + 'api/'
+    self.format = :json
+    self.include_root_in_json = true
+
+    cattr_accessor :locale
+    cattr_accessor :http_host
+
+    # @private
+    def self.element_name
+      @element_name ||= first_resource_child.model_name.element
     end
 
+    # @private
     @@deprecation_warnings = true
     cattr_writer :deprecation_warnings
 
+    # @private
     def self.deprecated(deprecated, hint = nil)
       return unless @@deprecation_warnings
       text = "[WebCrmConnector] #{deprecated} is deprecated."
@@ -24,21 +43,94 @@ module Infopark; module Crm; module Core
       end
     end
 
+    # @private
     def known_attributes
-      KnownAttributes.new(super)
+      Core::KnownAttributes.new(super)
     end
 
-    # Inheritable Resources
-    def self.defines_webservice?
-      true
+    ##
+    # @webcrm_todo remove when https://github.com/rails/rails/issues/2479 is done
+    # @private
+    def self.delete(id, options = {})
+      connection.delete(element_path(id, options), headers)
     end
 
-    def self.inherited(sub)
-      super
-      sub.__send__(:include, InheritingResource) unless sub.defines_webservice?
+    # @private
+    def self.headers
+      headers = super
+      headers.merge!({"Accept-Language" => self.locale}) if self.locale
+      headers.merge!({"Host" => self.http_host}) if self.http_host
+      headers
     end
 
-    # /Inheritable Resources
-  end
+    # @private
+    def self.configure(configuration)
+      self.site = configuration.url + '/api/' if configuration.url
+      self.user = configuration.login
+      self.password = configuration.api_key
+      self.locale = configuration.locale
+      self.http_host = configuration.http_host
+    end
+
+    # @private
+    def self.schema=(definition)
+      ares_compatible_definition = {}
+      definition.each do |k, v|
+        ares_compatible_definition[k] = SchemaSupport.schema_type(v)
+      end
+      super(ares_compatible_definition)
+    end
+
+    ###
+    # @webcrm_todo drop when ActiveResource 3.0 support is dropped
+    # @private
+    class SchemaSupport
+      def self.schema_mapping
+        @schema_mapping ||= {}
+      end
+
+      def self.add(mapping)
+        schema_mapping.merge!(mapping)
+      end
+
+      def self.schema_type(type)
+        default_mapping = ::ActiveResource::Schema::KNOWN_ATTRIBUTE_TYPES
+        return type if default_mapping.include?(type.to_s)
+        return schema_mapping[type.to_sym]
+      end
 
+      add :text => :string
+      add :date => :string
+      add :boolean => nil
+    end
+
+    # Support for field associatable errors (without humanized name guessing)
+    # @private
+    def errors
+      @errors ||= Errors.new(self)
+    end
+
+    # @private
+    class Errors < ActiveResource::Errors
+
+      ##
+      # @webcrm_todo temporary patch from https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/5616
+      def from_json(json, save_cache = false)
+        errors = ActiveSupport::JSON.decode(json)
+        clear unless save_cache
+        errors.each do |attr_name, messages|
+          Array.wrap(messages).each { |message| add(attr_name.to_sym, message) }
+        end
+      end
+
+    end
+
+    private
+
+    def self.first_resource_child
+      ancestors.each_cons(2) do |child, parent|
+        return child if (parent == Infopark::Crm::Core::Resource)
+      end
+    end
+  end
 end; end; end

data/lib/crm_connector/core/search_support.rb

@@ -1,5 +1,6 @@
-# :stopdoc:
 module Infopark; module Crm; module Core
+
+  # @private
   module SearchSupport
     def self.included(klass)
       klass.extend(ClassMethods)
@@ -18,4 +19,5 @@ module Infopark; module Crm; module Core
 
     end
   end
+
 end; end; end

data/lib/crm_connector/custom_type.rb

@@ -1,7 +1,24 @@
 module Infopark; module Crm
-  # This is an extendable class. See Default::CustomType for documentation
-  class CustomType < Default::CustomType
-    class CustomAttribute < Default::CustomType::CustomAttribute #:nodoc:
+  class CustomType < Core::Resource
+    self.schema = {
+      :custom_attributes => :hash,
+      :icon_css_class => :string,
+      :kind => :string,
+      :name => :string,
+      :states => :array,
+    }
+
+    # @private
+    class CustomAttribute < Core::Resource
+
+      self.include_root_in_json = false
+
+      ###
+      # @webcrm_todo this method is only needed until the deprecated Object#type is removed
+      #   Better: define self.schema
+      def type
+        attributes['type']
+      end
     end
   end
 end; end

data/lib/crm_connector/{default.rb → errors.rb}

@@ -1,6 +1,6 @@
 module Infopark
   module Crm
-    module Default
+    module Errors
       Infopark::Crm.setup_autoload(self, __FILE__)
     end
   end

data/lib/crm_connector/errors/authentication_failed.rb

@@ -0,0 +1,10 @@
+module Infopark; module Crm; module Errors
+
+  ##
+  # Raised when a contact provides wrong credentials (token/password)
+  #
+  # This differs from the case when the web services API credentials are not accepted
+  # (an ActiveResource error is raised then)
+  class AuthenticationFailed < Base; end
+
+end; end; end

data/lib/crm_connector/errors/base.rb

@@ -0,0 +1,8 @@
+module Infopark; module Crm; module Errors
+
+  ##
+  # Super class of all connector errors
+  class Base < StandardError
+  end
+
+end; end; end

data/lib/crm_connector/event.rb

@@ -1,4 +1,39 @@
 module Infopark; module Crm
-  # This is an extendable class. See Default::Event for documentation
-  class Event < Default::Event; end
+  class Event < Core::Resource
+
+    ##
+    # @!method self.search(input)
+    # Searches for events
+    # @param input [Hash] A hash containing a +params+ key. The value of this key is a hash containing the actual search query.
+    # @return [Array<Infopark::Crm::Event>]
+    # @webcrm_rest_url <code>GET /api/events/search</code>
+    # @example
+    #   results = Infopark::Crm::Event.search(:params => {:kind => kind})
+    #   results = Infopark::Crm::Event.search(:params => {:event_set => event_set})
+    #   results = Infopark::Crm::Event.search(:params => {:q => 'full-text search'})
+    has_search
+
+    self.schema = {
+      :custom_attributes => :hash,
+      :dtend_at => :time,
+      :dtstart_at => :time,
+      :event_set => :string,
+      :kind => :string,
+      :location => :string,
+      :title => :string,
+    }
+  end
+
+  # @private
+  class Event::CustomAttribute < Core::Resource
+
+    self.include_root_in_json = false
+
+    ##
+    # @webcrm_todo this method is only needed until the deprecated Object#type is removed
+    #   Better: define self.schema
+    def type
+      attributes['type']
+    end
+  end
 end; end

data/lib/crm_connector/event_contact.rb

@@ -1,4 +1,40 @@
 module Infopark; module Crm
-  # This is an extendable class. See Default::EventContact for documentation
-  class EventContact < Default::EventContact; end
+  class EventContact < Core::Resource
+
+    ##
+    # @!method self.search(input)
+    # Searches for event contacts
+    # @param input [Hash] A hash containing a +params+ key. The value of this key is a hash containing the actual search query.
+    # @return [Array<Infopark::Crm::EventContact>]
+    # @webcrm_rest_url <code>GET /api/event_contacts/search</code>
+    # @example
+    #   results = Infopark::Crm::EventContacts.search(:params => {:event_id => eid})
+    #   results = Infopark::Crm::EventContacts.search(:params => {:contact_id => cid})
+    #   results = Infopark::Crm::EventContacts.search(:params => {:state => state})
+    #   results = Infopark::Crm::EventContacts.search(:params => {:q => 'full-text search'})
+    has_search
+
+    self.schema = {
+      :state => :string,
+      :contact_id => :string,
+      :event_id => :string,
+    }
+
+    ##
+    # Queries the WebCRM for the Contact with the id +contact_id+.
+    # @return [Infopark::Crm::Contact] The contact associated with this event contact, if +contact_id+ is present.
+    # @webcrm_rest_url <code>GET /api/contacts/_contact_id_</code>
+    def contact
+      Infopark::Crm::Contact.find(contact_id) if contact_id
+    end
+
+    ##
+    # Queries the WebCRM for the Event with the id +event_id+.
+    # @return [Infopark::Crm::Event] The event associated with this event contact, if +event_id+ is present.
+    # @webcrm_rest_url <code>GET /api/events/_event_id_</code>
+    def event
+      Infopark::Crm::Event.find(event_id) if event_id
+    end
+
+  end
 end; end

data/lib/crm_connector/mailing.rb

@@ -1,4 +1,37 @@
 module Infopark; module Crm
-  # This is an extendable class. See Default::Mailing for documentation
-  class Mailing < Default::Mailing; end
+  class Mailing < Core::Resource
+
+    ##
+    # @!method self.search(input)
+    # Searches for mailings
+    # @param input [Hash] A hash containing a +params+ key. The value of this key is a hash containing the actual search query.
+    # @return [Array<Infopark::Crm::Mailing>]
+    # @webcrm_rest_url <code>GET /api/mailings/search</code>
+    # @example
+    #   results = Infopark::Crm::Mailing.search(:params => {:event_id => event_id})
+    #   results = Infopark::Crm::Mailing.search(:params => {:only_unreleased => true})
+    #   results = Infopark::Crm::Mailing.search(:params => {:q => 'full-text search'})
+    has_search
+
+    self.schema = {
+      :body => :string,
+      :dtstart_at => :time,
+      :email_from => :string,
+      :email_reply_to => :string,
+      :email_subject => :string,
+      :event_id => :string,
+      :html_body => :string,
+      :mailing_type => :string,
+      :title => :string,
+    }
+
+    ##
+    # Queries the WebCRM for the Event with the id +event_id+.
+    # @return [Infopark::Crm::Event] The event associated with this event contact, if +event_id+ is present.
+    # @webcrm_rest_url <code>GET /api/events/_event_id_</code>
+    def event
+      Infopark::Crm::Event.find(event_id) if event_id
+    end
+  end
+
 end; end

data/lib/crm_connector/role.rb

@@ -1,4 +1,9 @@
 module Infopark; module Crm
-  # This is an extendable class. See Default::Role for documentation
-  class Role < Default::Role; end
+  class Role < Core::Resource
+    self.schema = {
+      :description => :string,
+      :name => :string,
+      :permissions => :array,
+    }
+  end
 end; end