fotolia 0.0.1

data/lib/fotolia/categories.rb

@@ -0,0 +1,53 @@
+module Fotolia
+  #
+  # Base class for ConceptualCategories and RepresentativeCategories.
+  #
+  class Categories
+    #
+    # == Parameters
+    # fotolia_client:: A Fotolia::Base object
+    #
+    def initialize(fotolia_client)
+      @fotolia = fotolia_client
+    end
+
+    #
+    # Returns an array of Category objects. If no category is given, fetches
+    # the root level category. Otherwise the child categories of the given cat
+    # are returned.
+    #
+    # Raises a RuntimeError if not called on a ConceptualCategories or
+    # RepresentativeCategories object, i. e. <tt>@method</tt> and
+    # <tt>@klass</tt> has to be set.
+    #
+    def find(category = nil)
+      raise 'You have to use ConceptualCategories or RepresentativeCategories!' unless(@method && @klass)
+
+      k = if(category) then category.id else :root end
+
+      if(@categories && @categories[k]) # check if categories have been loaded already
+        @categories[k] # use cached categories
+      else
+        # get cats from fotolia
+        res = if(category && (category.kind_of?(String) || category.kind_of?(Fixnum)))
+          @fotolia.remote_call(@method, @fotolia.language.id, category.to_i)
+        elsif(category)
+          @fotolia.remote_call(@method, @fotolia.language.id, category.id.to_i)
+        else
+          @fotolia.remote_call(@method, @fotolia.language.id)
+        end
+
+        @categories = Hash.new unless(@categories)
+
+        @categories[k] = res.collect{|c| @klass.new(@fotolia, {'key' => c.first, 'parent_category' => category}.merge(c.last))}
+      end
+    end
+
+    #
+    # Returns an array of all root level Category objects. See #find.
+    #
+    def root_level
+      self.find
+    end
+  end
+end

data/lib/fotolia/category.rb

@@ -0,0 +1,23 @@
+module Fotolia
+  #
+  # Base class for ConceptualCategory and RepresentativeCategory.
+  #
+  class Category
+    # <Integer> The category's id at Fotolia
+    attr_reader :id
+    # <String> The category's name at Fotolia. Should be translated to the language the used Fotolia::Base object is set to.
+    attr_reader :name
+    # <Category> The parent of this category or nil if any.
+    attr_reader :parent_category
+    # <String> Don't know what this attribute means, but Fotolia's API delivers it...
+    attr_reader :key
+
+    def initialize(fotolia_client, attributes)
+      @fotolia = fotolia_client
+      @id = attributes['id'].to_i
+      @name = attributes['name']
+      @parent_category = attributes['parent_category']
+      @key = attributes['key']
+    end
+  end
+end

data/lib/fotolia/color.rb

@@ -0,0 +1,14 @@
+module Fotolia
+  #
+  # Represents a color at Fotolia.
+  #
+  class Color
+    attr_reader :id
+    attr_reader :name
+
+    def initialize(attributes)
+      @id = attributes[:id]
+      @name = attributes[:name]
+    end
+  end
+end

data/lib/fotolia/colors.rb

@@ -0,0 +1,39 @@
+module Fotolia
+  #
+  # Class fetching colors known to Fotolia's API.
+  #
+  # You should use Fotolia::Base#colors as shortcut instead of creating own
+  # instances.
+  #
+  class Colors
+    def initialize(fotolia_client)
+      @fotolia = fotolia_client
+    end
+
+    #
+    # Fetches colors from Fotolia's API and returns them as Array of
+    # Fotolia::Color objects.
+    #
+    # Colors at Fotolia may have children. Not passing anything to this method
+    # returns all root level colors. Passing a Fotolia::Color object returns
+    # its children.
+    #
+    def find_all(parent_color = nil)
+      rsp = if(parent_color.kind_of?(Fotolia::Color))
+        @fotolia.remote_call('getColors', parent_color.id)
+      elsif(parent_color)
+        @fotolia.remote_call('getColors', parent_color.to_i)
+      else
+        @fotolia.remote_call('getColors')
+      end
+
+      ret = Array.new
+
+      rsp['colors'].each_value do |color_response|
+        ret << Fotolia::Color.new(:id => color_response['id'].to_i, :name => color_response['name'])
+      end
+
+      ret
+    end
+  end
+end

data/lib/fotolia/conceptual_categories.rb

@@ -0,0 +1,15 @@
+module Fotolia
+  #
+  # An interface to the conceptual categories at Fotolia.
+  #
+  # You should consider using Fotolia::Base#conceptual_categories as shortcut
+  # to an instance of this class.
+  #
+  class ConceptualCategories < Categories
+    def initialize(fotolia_client)
+      @method = 'getCategories2'
+      @klass = ConceptualCategory
+      super(fotolia_client)
+    end
+  end
+end

data/lib/fotolia/conceptual_category.rb

@@ -0,0 +1,24 @@
+module Fotolia
+  #
+  # Represents a conceptual category at Fotolia.
+  #
+  class ConceptualCategory < Category
+    #
+    # Returns an array of ConceptualCategory objects which are children of this
+    # category.
+    #
+    def child_categories
+      @fotolia.conceptual_categories.find(self)
+    end
+
+    #
+    # Searches for media in this category. For the options hash, see
+    # Fotolia::Base#search.
+    #
+    # Returns a Fotolia::SearchResultSet.
+    #
+    def media(options = {})
+      @fotolia.search(options.merge({:conceptual_category => self}))
+    end
+  end
+end

data/lib/fotolia/countries.rb

@@ -0,0 +1,21 @@
+module Fotolia
+  #
+  # Fetches all countries known to Fotolia from its API.
+  #
+  # You may use Fotolia::Base#countries as shortcut to an instance of this class.
+  #
+  class Countries
+    def initialize(fotolia_client)
+      @fotolia = fotolia_client
+    end
+
+    #
+    # Returns an array of Fotolia::Country objects.
+    #
+    def find_all
+      rsp = @fotolia.remote_call('getCountries', @fotolia.language.id)
+
+      rsp.collect{|c| Fotolia::Country.new(c)}
+    end
+  end
+end

data/lib/fotolia/country.rb

@@ -0,0 +1,14 @@
+module Fotolia
+  #
+  # Represents one country at Fotolia.
+  #
+  class Country
+    attr_reader :id
+    attr_reader :name
+
+    def initialize(attributes)
+      @id = attributes['id'].to_i
+      @name = attributes['name']
+    end
+  end
+end

data/lib/fotolia/galleries.rb

@@ -0,0 +1,36 @@
+module Fotolia
+  #
+  # Interface to galleries at Fotolia.
+  #
+  # Use Fotolia::Base#galleries as shortcut to an instance of this class.
+  #
+  class Galleries
+    def initialize(fotolia_client)
+      @fotolia = fotolia_client
+    end
+
+    #
+    # Returns public galleries in an array (of Fotolia::Gallery objects).
+    #
+    def find_all
+      rsp = @fotolia.remote_call('getGalleries', @fotolia.language.id)
+
+      rsp.collect{|g| Fotolia::Gallery.new(@fotolia, g)}
+    end
+
+    #
+    # Creates a gallery for the logged in user.
+    #
+    # Requires an authenticated session, see Fotolia::Base#login.
+    #
+    # Not working with Partner API.
+    #
+    def create(name)
+      raise Fotolia::LoginRequiredError unless @fotolia.logged_in?
+
+      res = @fotolia.remote_call('createUserGallery', @fotolia.session_id, name)
+
+      Fotolia::Gallery.new(@fotolia, {'id' => res['id'], 'name' => name})
+    end
+  end
+end

data/lib/fotolia/gallery.rb

@@ -0,0 +1,65 @@
+module Fotolia
+  #
+  # Represents a gallery at Fotolia.
+  #
+  class Gallery
+    attr_reader :name, :thumbnail_width, :thumbnail_html_tag, :id, :nb_media,
+      :thumbnail_height, :thumbnail_url
+
+    #
+    # == Parameters
+    # fotolia_client:: A Fotolia::Base object.
+    # attributes:: An hash containing the keys 'name', 'id', 'nb_media' and
+    #              optional 'thumbnail_width', 'thumbnail_height',
+    #              'thumbnail_html_tag' and 'thumbnail_url'.
+    #
+    def initialize(fotolia_client, attributes)
+      @fotolia = fotolia_client
+      
+      @name = attributes['name']
+      @thumbnail_width = attributes['thumbnail_width'] if(attributes['thumbnail_width'])
+      @thumbnail_html_tag = attributes['thumbnail_html_tag'] if(attributes['thumbnail_html_tag'])
+      @id = attributes['id']
+      @nb_media = attributes['nb_media']
+      @thumbnail_height = attributes['thumbnail_height'] if(attributes['thumbnail_height'])
+      @thumbnail_url = attributes['thumbnail_url'] if(attributes['thumbnail_url'])
+    end
+
+    #
+    # Returns the media in this gallery.
+    #
+    # ==options hash
+    # See Fotolia::Base#search
+    #
+    # ==Returns
+    # Fotolia::SearchResultSet
+    #
+    def media(options = {})
+      @fotolia.search(options.merge({:gallery => self}))
+    end
+
+    #
+    # Deletes the gallery.
+    #
+    # Requires an authenticated session. The logged in user has to be the owner
+    # of the gallery.
+    #
+    # Not available in Partner API.
+    #
+    def delete
+      raise Fotolia::LoginRequiredError unless @fotolia.logged_in?
+      @fotolia.remote_call('deleteUserGallery', @fotolia.session_id, self.id)
+    end
+
+    #
+    # Add a medium to this gallery. The gallery has to be owned by the logged in
+    # user, so this methods requires an authenticated session. See
+    # Fotolia::Base#login.
+    #
+    # Not available in Partner API.
+    #
+    def << (medium)
+      medium.add_to_user_gallery(self)
+    end
+  end
+end

data/lib/fotolia/language.rb

@@ -0,0 +1,58 @@
+module Fotolia
+  # Error class raised if an unknwon symbol or id is given to Fotolia::Language#new.
+  class LanguageNotDefinedError < StandardError; end
+
+  #
+  # Represents a language at Fotolia. An object of this class may be given to
+  # Fotolia::Base#new:
+  #
+  #   language = Fotolia::Language.new :de
+  #   fotolia = Fotolia.new :api_key => 'AAAAA...', :language => language
+  #
+  # Most API calls on the fotolia object will deliver translated results then.
+  #
+  class Language
+
+    #
+    # Translate language code-like symbols to their ids at Fotolia.
+    #
+    LANGUAGE_IDS = {
+      :fr => 1,
+      :en_us => 2,
+      :en_uk => 3,
+      :de => 4,
+      :es => 5,
+      :it => 6,
+      :pt_pt => 7,
+      :pt_br => 8,
+      :jp => 9,
+      :pl => 11
+    }
+
+    def initialize(id_or_lang_sym)
+      if(id_or_lang_sym.is_a?(Symbol))
+        raise Fotolia::LanguageNotDefinedError and return nil unless(LANGUAGE_IDS.has_key?(id_or_lang_sym))
+        @language_sym = id_or_lang_sym
+      else
+        raise Fotolia::LanguageNotDefinedError and return nil unless(LANGUAGE_IDS.has_value?(id_or_lang_sym))
+        @language_sym = LANGUAGE_IDS.invert[id_or_lang_sym]
+      end
+
+      self
+    end
+
+    def to_s
+      @language_sym.to_s
+    end
+    
+    alias to_code to_s
+
+    def to_sym
+      @language_sym
+    end
+
+    def id
+      LANGUAGE_IDS[@language_sym]
+    end
+  end
+end

data/lib/fotolia/medium.rb

@@ -0,0 +1,348 @@
+module Fotolia
+  #
+  # Represents a medium in Fotolia's database.
+  #
+  class Medium
+    #
+    # A thumbnail attached to a Medium object. Just holds its url, width, height
+    # and an html tag to include it on web pages.
+    #
+    class Thumbnail
+      attr_reader :url, :html_tag, :width, :height
+
+      def initialize(attributes)
+        @url = attributes['thumbnail_url']
+        @html_tag = attributes['thumbnail_html_tag']
+        @width = attributes['thumbnail_width']
+        @height = attributes['thumbnail_height']
+      end
+    end
+
+    #
+    # Represents a license in which Fotolia's media are available.
+    #
+    # See http://www.fotolia.com/Info/SizesAndUses for an overview of available
+    # licenses.
+    #
+    class License
+      attr_reader :name, :price
+
+      def initialize(medium, attributes)
+        @medium = medium
+        @name = attributes['name']
+        @price = attributes['price']
+      end
+
+      def width
+        begin
+          @width ||= @medium.details['licenses_details'][self.name]['width']
+        rescue
+          nil
+        end
+      end
+
+      def height
+        begin
+          @height ||= @medium.details['licenses_details'][self.name]['height']
+        rescue
+          nil
+        end
+      end
+
+      def dpi
+        begin
+          @dpi ||= @medium.details['licenses_details'][self.name]['dpi']
+        rescue
+          nil
+        end
+      end
+
+      def ratio
+        begin
+          @ratio ||= @medium.details['licenses_details'][self.name]['ratio']
+        rescue
+          nil
+        end
+      end
+
+      def phrase
+        begin
+          @phrase ||= @medium.details['licenses_details'][self.name]['phrase']
+        rescue
+          nil
+        end
+      end
+    end
+
+    #
+    # I never got to know what a CompImage should be, least Fotolia's API has a
+    # method to get one for a medium. So this is a class holding the info that
+    # method returns.
+    #
+    class CompImage
+      attr_reader :url, :width, :height
+
+      def initialize(attributes)
+        @url = attributes['url']
+        @width = attributes['width']
+        @height = attributes['height']
+      end
+
+      def self.find(medium)
+        CompImage.new(medium.fotolia.remote_call('getMediaComp', medium.id))
+      end
+    end
+
+    #
+    # Fotolia has media in three types: Photo, illustration and vector. In the
+    # API they are referenced by ids, so we keep this hash to ease the handling
+    # for human developers...
+    #
+    MEDIA_TYPES = {1 => :photo, 2 => :illustration, 3 => :vector}
+
+    # The id of the medium in Fotolia's DB.
+    attr_reader :id
+    #
+    # The thumbnail attached to the medium. Note that its size may vary
+    # according to the :thumbnail_size option you give at Base#search.
+    #
+    attr_reader :thumbnail
+    # An array of Licenses the medium is available in.
+    attr_reader :licenses
+    attr_reader :fotolia #:nodoc:
+
+    #
+    # Needs an instance of Fotolia::Base (so you won't have to give the API_KEY
+    # each time you call a method which requires interaction with the API) and
+    # some attributes as parameters.
+    #
+    #   Fotolia::Medium.new Fotolia.new(:api_key => 'AAA...'), :id => 12345678
+    #
+    # should be enough to get a valid object -- missing values will be collected
+    # from the API automatically (with an default size of 400px for the
+    # thumbnail).
+    #
+    def initialize(fotolia_client, attributes)
+      @fotolia = fotolia_client
+      @id = attributes['id'].to_i
+      @title = attributes['title'] if(attributes['title'])
+      @creator_id = attributes['creator_id'] if(attributes['creator_id'])
+      @creator_name = attributes['creator_name'] if(attributes['creator_name'])
+      @thumbnail = Thumbnail.new(attributes) if(attributes['thumbnail_url'])
+      @nb_views = attributes['nb_views'] if(attributes['nb_views'])
+      @nb_downloads = attributes['nb_downloads'] if(attributes['nb_downloads'])
+      @keywords = attributes['keywords'].split(',').collect{|k| k.strip} if(attributes['keywords'])
+      @licenses = attributes['licenses'].collect{|l| License.new(self, l)} if(attributes['licenses'])
+    end
+
+    #
+    # See Fotolia::Medium::CompImage
+    #
+    def comp_image
+      @comp_image ||= CompImage.find(self)
+    end
+
+    def details #:nodoc:
+      @details ||= @fotolia.remote_call('getMediaData', self.id, 400, @fotolia.language.id)
+    end
+
+    #
+    # Returns the number of times this medium has been viewed on Fotolia's page.
+    #
+    def nb_views
+      @nb_views ||= self.details['nb_views']
+    end
+
+    #
+    # Returns the number of times this medium has been purchased at Fotolia.
+    #
+    def nb_downloads
+      @nb_downloads ||= self.details['nb_downloads']
+    end
+
+    #
+    # Returns an array of keywords attached to this medium. May be translated to
+    # the language the client has been set to, but don't rely on it.
+    #
+    def keywords
+      unless(@keywords)
+        @keywords = []
+        @keywords = self.details['keywords'].collect{|k| k['name']} if(self.details['keywords'])
+      end
+      @keywords
+    end
+
+    #
+    # Returns the Fotolia::Country object associated with this medium.
+    #
+    def country
+      @country ||= Fotolia::Country.new({'id' => self.details['country_id'], 'name' => self.details['country_name']})
+    end
+
+    #
+    # Returns the Fotolia::ConceptualCategory object this medium is in.
+    #
+    # If the medium is in a child or grand-child category of the root level, the
+    # parent relations will be set properly. Call
+    # <tt>medium.conceptual_category.parent_category</tt> to use this feature.
+    #
+    def conceptual_category
+      #@conceptual_category ||= (self.details['cat2'] ? Fotolia::ConceptualCategory.new(@fotolia, self.details['cat2']) : nil)
+      unless(@conceptual_category)
+        @conceptual_category = if(self.details['cat2_hierarchy'])
+          cats = Array.new
+          self.details['cat2_hierarchy'].each_with_index do |cat, i|
+            parent = if(i > 0 && cats[i - 1]) then cats[i - 1] else nil end
+            cats[i] = Fotolia::ConceptualCategory.new(@fotolia, {'parent_category' => parent}.merge(cat))
+          end
+          cats.last
+        else
+          nil
+        end
+      end
+      @conceptual_category
+    end
+
+    #
+    # Same as Fotolia::Medium#conceptual_category, but returns the associated
+    # Fotolia::RepresentativeCategory instead.
+    #
+    def representative_category
+      #@representative_category ||= (self.details['cat1'] ? Fotolia::RepresentativeCategory.new(@fotolia, self.details['cat1']) : nil)
+      unless(@representative_category)
+        @representative_category = if(self.details['cat1_hierarchy'])
+          cats = Array.new
+          self.details['cat1_hierarchy'].each_with_index do |cat, i|
+            parent = if(i > 0 && cats[i - 1]) then cats[i - 1] else nil end
+            cats[i] = Fotolia::RepresentativeCategory.new(@fotolia, {'parent_category' => parent}.merge(cat))
+          end
+          cats.last
+        else
+          nil
+        end
+      end
+      @representative_category
+    end
+
+    #
+    # Returns the media type id used by Fotolia's API. See MEDIA_TYPES and
+    # #media_type
+    #
+    def media_type_id
+      @media_type_id ||= self.details['media_type_id']
+    end
+
+    #
+    # Returns the media type of this medium as symbol. May be one of :photo,
+    # :illustration, :vector or -- in desperate cases -- :unknown.
+    #
+    def media_type
+      MEDIA_TYPES[self.media_type_id] || :unknown
+    end
+
+    # No need for explanation, isn't there?
+    def title
+      @title ||= self.details['title']
+    end
+
+    # The id of the medium's creator. May be used to find more media by the same
+    # creator.
+    def creator_id
+      @creator_id ||= self.details['creator_id']
+    end
+
+    # The name of the creator.
+    def creator_name
+      @creator_name ||= self.details['creator_name']
+    end
+
+    #
+    # An array of licenses the medium is available in. See
+    # Fotolia::Medium::License.
+    #
+    def licenses
+      @licenses ||= self.details['licenses'].collect{|l| License.new(self, l)}
+    end
+
+    #
+    # A thumbnail for this medium. See Fotolia::Medium::Thumbnail.
+    #
+    def thumbnail
+      @thumbnail ||= Thumbnail.new(self.details)
+    end
+
+    # Returns true if this medium is a photo.
+    def is_photo?
+      :photo == self.media_type
+    end
+
+    # Returns true if this medium is an illustration.
+    def is_illustration?
+      :illustration == self.media_type
+    end
+
+    # Returns true if this medium is a vector image.
+    def is_vector?
+      :vector == self.media_type
+    end
+
+    #
+    # Searches for similar media to this medium.
+    #
+    # Note that this method takes the same options hash as Fotolia::Base#search.
+    #
+    def similar_media(options = {})
+      @fotolia.search(options.merge({:similia_id => self.id}))
+    end
+
+    # TODO:: implement function
+    #
+    # Does not work in Partner and Developer API.
+    #
+    def buy_and_save_as(license, file_path) #:nodoc:
+    end
+
+    #
+    # Adds this medium to the logged in user's lightbox or one of his galleries.
+    #
+    # Requires an authenticated session. Call Fotolia::Base#login on the fotolia
+    # client object used to get this medium object first!
+    #
+    # ==Parameters
+    # gallery:: A Fotolia::Gallery object or nil. If the latter, the user's lightbox is used.
+    #
+    # Does not work in Partner API.
+    #
+    def add_to_user_gallery(gallery = nil)
+      raise Fotolia::LoginRequiredError unless @fotolia.logged_in?
+
+      if(gallery)
+        # add to gallery
+        @fotolia.remote_call('addToUserGallery', @fotolia.session_id, self.id, gallery.id)
+      else
+        # add to lightbox
+        @fotolia.remote_call('addToUserGallery', @fotolia.session_id, self.id)
+      end
+    end
+
+    #
+    # Removes this medium from the logged in user's gallery or lightbox.
+    #
+    # Requires an authenticated session. Call Fotolia::Base#login first!
+    #
+    # ==Parameters
+    # gallery:: A Fotolia::Gallery object or nil. If the latter, the user's lightbox is used.
+    #
+    # Does not work in Partner API.
+    #
+    def remove_from_user_gallery(gallery = nil)
+      raise Fotolia::LoginRequiredError unless @fotolia.logged_in?
+
+      if(gallery)
+        @fotolia.remote_call('removeFromUserGallery', @fotolia.session_id, self.id, gallery.id)
+      else
+        @fotolia.remote_call('removeFromUserGallery', @fotolia.session_id, self.id)
+      end
+    end
+  end
+end