Class: Fotolia::Medium

Inherits:
Object
  • Object
show all
Defined in:
lib/fotolia/medium.rb

Overview

Represents a medium in Fotolia’s database.

Defined Under Namespace

Classes: CompImage, License, Thumbnail

Constant Summary collapse

MEDIA_TYPES =

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…

{1 => :photo, 2 => :illustration, 3 => :vector}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(fotolia_client, attributes) ⇒ Medium

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).



125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/fotolia/medium.rb', line 125

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

Instance Attribute Details

#fotolia ⇒ Object (readonly)

:nodoc:



112
113
114
 
# File 'lib/fotolia/medium.rb', line 112

def fotolia
  @fotolia
end

#id ⇒ Object (readonly)

The id of the medium in Fotolia’s DB.



104
105
106
 
# File 'lib/fotolia/medium.rb', line 104

def id
  @id
end

#licenses ⇒ Object (readonly)

An array of licenses the medium is available in. See Fotolia::Medium::License.



111
112
113
 
# File 'lib/fotolia/medium.rb', line 111

def licenses
  @licenses
end

#thumbnail ⇒ Object (readonly)

A thumbnail for this medium. See Fotolia::Medium::Thumbnail.



109
110
111
 
# File 'lib/fotolia/medium.rb', line 109

def thumbnail
  @thumbnail
end

Instance Method Details

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.

Raises:



316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/fotolia/medium.rb', line 316

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

#buy_and_save_as(license, file_path) ⇒ Object

TODO

implement function

Does not work in Partner and Developer API.



302
303
 
# File 'lib/fotolia/medium.rb', line 302

def buy_and_save_as(license, file_path) #:nodoc:
end

#comp_image ⇒ Object

See Fotolia::Medium::CompImage



141
142
143
 
# File 'lib/fotolia/medium.rb', line 141

def comp_image
  @comp_image ||= CompImage.find(self)
end

#conceptual_category ⇒ Object

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 medium.conceptual_category.parent_category to use this feature.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/fotolia/medium.rb', line 189

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

#country ⇒ Object

Returns the Fotolia::Country object associated with this medium.



178
179
180
 
# File 'lib/fotolia/medium.rb', line 178

def country
  @country ||= Fotolia::Country.new({'id' => self.details['country_id'], 'name' => self.details['country_name']})
end

#creator_id ⇒ Object

The id of the medium’s creator. May be used to find more media by the same creator.



250
251
252
 
# File 'lib/fotolia/medium.rb', line 250

def creator_id
  @creator_id ||= self.details['creator_id']
end

#creator_name ⇒ Object

The name of the creator.



255
256
257
 
# File 'lib/fotolia/medium.rb', line 255

def creator_name
  @creator_name ||= self.details['creator_name']
end

#details ⇒ Object

:nodoc:



145
146
147
 
# File 'lib/fotolia/medium.rb', line 145

def details #:nodoc:
  @details ||= @fotolia.remote_call('getMediaData', self.id, 400, @fotolia.language.id)
end

#is_illustration? ⇒ Boolean

Returns true if this medium is an illustration.

Returns:

  • (Boolean) 


280
281
282
 
# File 'lib/fotolia/medium.rb', line 280

def is_illustration?
  :illustration == self.media_type
end

#is_photo? ⇒ Boolean

Returns true if this medium is a photo.

Returns:

  • (Boolean) 


275
276
277
 
# File 'lib/fotolia/medium.rb', line 275

def is_photo?
  :photo == self.media_type
end

#is_vector? ⇒ Boolean

Returns true if this medium is a vector image.

Returns:

  • (Boolean) 


285
286
287
 
# File 'lib/fotolia/medium.rb', line 285

def is_vector?
  :vector == self.media_type
end

#keywords ⇒ Object

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.



167
168
169
170
171
172
173
 
# File 'lib/fotolia/medium.rb', line 167

def keywords
  unless(@keywords)
    @keywords = []
    @keywords = self.details['keywords'].collect{|k| k['name']} if(self.details['keywords'])
  end
  @keywords
end

#media_type ⇒ Object

Returns the media type of this medium as symbol. May be one of :photo, :illustration, :vector or – in desperate cases – :unknown.



239
240
241
 
# File 'lib/fotolia/medium.rb', line 239

def media_type
  MEDIA_TYPES[self.media_type_id] || :unknown
end

#media_type_id ⇒ Object

Returns the media type id used by Fotolia’s API. See MEDIA_TYPES and #media_type



231
232
233
 
# File 'lib/fotolia/medium.rb', line 231

def media_type_id
  @media_type_id ||= self.details['media_type_id']
end

#nb_downloads ⇒ Object

Returns the number of times this medium has been purchased at Fotolia.



159
160
161
 
# File 'lib/fotolia/medium.rb', line 159

def nb_downloads
  @nb_downloads ||= self.details['nb_downloads']
end

#nb_views ⇒ Object

Returns the number of times this medium has been viewed on Fotolia’s page.



152
153
154
 
# File 'lib/fotolia/medium.rb', line 152

def nb_views
  @nb_views ||= self.details['nb_views']
end

#remove_from_user_gallery(gallery = nil) ⇒ Object

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.

Raises:



338
339
340
341
342
343
344
345
346
 
# File 'lib/fotolia/medium.rb', line 338

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

#representative_category ⇒ Object

Same as Fotolia::Medium#conceptual_category, but returns the associated Fotolia::RepresentativeCategory instead.



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/fotolia/medium.rb', line 210

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

#similar_media(options = {}) ⇒ Object

Searches for similar media to this medium.

Note that this method takes the same options hash as Fotolia::Base#search.



294
295
296
 
# File 'lib/fotolia/medium.rb', line 294

def similar_media(options = {})
  @fotolia.search(options.merge({:similia_id => self.id}))
end

#title ⇒ Object

No need for explanation, isn’t there?



244
245
246
 
# File 'lib/fotolia/medium.rb', line 244

def title
  @title ||= self.details['title']
end