simplificator-rwebthumb 0.0.6 → 0.1.0

data/README

@@ -4,12 +4,12 @@
 A Ruby wrapper for the webthumb API from http://webthumb.bluga.net
 
 = dependencies
- - tzinfo:http://tzinfo.rubyforge.org (install: sudo gem install tzinfo)
+ * tzinfo:http://tzinfo.rubyforge.org (install: sudo gem install tzinfo)
 
 = Installation
 sudo gem update --system (in case you are not yet on version 1.2.0 or higher)
 sudo gem sources -a http://gems.github.com (only once)
-sudo gem install rwebthumb
+sudo gem install simplificator-rwebthumb
 
 
 = Usage
@@ -37,7 +37,7 @@ job.fetch_when_complete(:large)
 # once thumbnails are fetched they are cached within the job. so a new fetch will not go to the server again
 
 # there is a helper method to write the images to disk
-job.write_file(, '/tmp/test.jpg')
+job.write_file(job.fetch(:custom), '/tmp/test.jpg')
 
 # if you have a job ID then you can use this to get a Job object and then use the fetch_xyz methods
 wt.job_status(JOB_ID)

data/lib/rwebthumb/job.rb

@@ -15,14 +15,23 @@ module Simplificator
         submission_datetime = self.parse_webthumb_datetime(job_element.attributes['time'])
         Job.new(api_key, job_element.text, job_element.attributes['url'], submission_datetime, job_element.attributes['estimate'].to_i, job_element.attributes['cost'].to_i)
       end 
-      
+      # Factory method to create a Job object from a status XML.
+      # this does not set all attributes of the Job (url, duration_estimate, cost) since the API of webthumb does not
+      # return the same information on job creation and status requests.
       def self.from_status_xml(api_key, xml)
         status_element = REXML::XPath.first(xml, '/webthumb/jobStatus/status')
         submission_datetime = self.parse_webthumb_datetime(status_element.attributes['submissionTime'])
         job = Job.new(api_key, status_element.attributes['id'], nil, submission_datetime, 5, nil, 
           status_element.text == 'Complete' ? STATUS_PICKUP : STATUS_PROCESSING)
       end
-    
+      # Constructor.
+      # *api_key: webthumb API key. Required by all the operations which query the server
+      # *job_id: id of the job. Required.
+      # *url: the url of the site to snapshot. Optional
+      # *submission_datetime: UTC Datetime of job submission
+      # *duration_estimate: integer value indicating estimated job duration in seconds
+      # *cost: integer value indicating how many credit this request costet. Optional
+      # *status: one of the STATUS_XXX constants defined in Base. Defaults to STATUS_PROCESSING
       def initialize(api_key, job_id, url, submission_datetime, duration_estimate, cost, status = STATUS_PROCESSING)
         super(api_key)
         @job_id = job_id
@@ -34,12 +43,14 @@ module Simplificator
         @cache = {}
       end
     
+      # Checks the status of the job on webthumb server.
+      # Returns one of the STATUS_XXX constants from Base.
+      # A call to this method updates the @status attribute.
       def check_status
         response = do_request(build_status_xml())
         @status = REXML::XPath.first(response, '/webthumb/jobStatus/status').text == 'Complete' ? STATUS_PICKUP : STATUS_PROCESSING
         if pickup?
           @completion_time = response.attributes['completionTime']
-          @duration = 'not yet... need to convert times first' 
         end
         @status
       end
@@ -52,6 +63,10 @@ module Simplificator
         fetch(size)
       end
       
+      # Fetch an image from the webthumb server.
+      # If the job has not yet finished then the server will return an error so check status first or use fetch_when_complete()
+      # Images are cached in the context of this Job so consequent calls are not requested from server again.
+      # Cache is experimental, dont know if it is a good idea.
       def fetch(size = :small)
         unless @cache.has_key?(size)
           response = do_request(build_fetch_xml(size))
@@ -60,6 +75,10 @@ module Simplificator
         @cache[size]
       end
       
+      # Write the data to disk.
+      # *data: the bytes of the image as returned by fetch/fetch_when_complete
+      # *name: a filename
+      # Will return a File object
       def write_file(data, name)
         raise WebthumbException.new('NO data given') if data == nil || data.size == 0
         File.open(name, 'wb+') do |file|
@@ -69,9 +88,11 @@ module Simplificator
         end
       end
       
+      # Is the status attribute set to STATUS_PICKUP ?
       def pickup?
         @status == STATUS_PICKUP
       end	
+      # Is the status attribute set to STATUS_PROCESSING ?
       def processing?
         @status == STATUS_PROCESSING
       end

data/lib/rwebthumb/webthumb.rb

@@ -4,21 +4,54 @@ require 'date'
 module Simplificator
   module Webthumb
 
-	
+    #
+    # Main access point for the webthumb API.
+    # All methods calling the Server need the api key beeing set.
+    #
     class Webthumb < Base
+      # Request thumbnail creation from webthumb server. A Job object holding 
+      # request information is returned (most important the job_id)
+      # Some keys have been ruby-ized (i.e. outputType -> :output_type). All keys are
+      # Symbols. Check out the webthumb API description for detailed explanation of the options
+      # http://webthumb.bluga.net/apidoc
+      # Options:
+      # * url: the url to take the snapshot from
+      # * output_type: chose output format (jpg or png)
+      # * width: width of the browser
+      # * height: height of the browser
+      # * fullthumb: full sized snapshot (true or false)
+      # * custom_thumbnail: create a custom sized thumbnail. A hash with width and height entries
+      # * effect: specify a visual effect (mirror, dropshadow or border)
+      # * delay: wait until the snapshot is taken
+      # * notify: callback url which is called after snapshot is taken
+      # * excerpt: taking an excerpt snapshot. A hash with for entries. width, height, x, y
+      # * videothumb: experimental option, check Joshs blog (http://blog.joshuaeichorn.com/archives/2008/07/08/videothumb-addon-to-webthumb-is-alpha/)
+      #   (true or false)
+      # Only the url option is required. Check webthumb API for default values. Check also the different constants 
+      # defined in Base.rb for valid values
+      #
       def thumbnail(options = {})
         Job.from_thumbnail_xml(@api_key, do_request(build_thumbnail_xml(options)))
       end
-
+      
+      # Request the job status from server.
+      # This can be used to look up job status from server when you just have the job ID, e.g. when you want to retrieve
+      # the thumbs later or when you use callbacks.
+      # The Job object returned from this method does not have all attributes set since. Webthumbs API does not return
+      # the requested URL, the duration estimation and the cost values when checking the status. I hope this will change someday.
       def job_status(job_id)
+        raise WebthumbException.new('Job id is required') if job_id == nil || job_id == ''
         Job.from_status_xml(@api_key, do_request(build_job_status_xml(job_id)))
       end
       
+      # Check your credit status on the webthumbs server
+      # Returns a hash with two keys. See webthumb API for detailed information.
+      # * reserve: an integer
+      # * subscription: an integer
       def credits()
-        root = build_root_node()
-        root.add_element('credits')
-        elements = do_request(root).elements['webthumb'].elements['credits'].elements
-        {:reserve => elements['reserve'].text.to_i, :subscription => elements['subscription'].text.to_i}
+        response = do_request(build_credits_xml())
+        credit_element = REXML::XPath.first(response, '/webthumb/credits')
+        {:reserve => credit_element['reserve'].text.to_i, :subscription => credit_element['subscription'].text.to_i}
       end
       
       private 
@@ -30,11 +63,15 @@ module Simplificator
         request = root.add_element('request')
         request.add_element('url').add_text(options[:url])
         add_element(request, options, :output_type, 'outputType')
-        [:width, :height, :effect, :delay, :notofy].each {|item| add_element(request, options, item)}
-			
+        # these elements have the same name as the key in options hash
+        [:width, :height, :effect, :delay, :notify].each {|item| add_element(request, options, item)}
+        # these options need conversion from true/false to 0/1
         if options[:fullthumb] == true
           request.add_element('fullthumb').add_text('1')
         end
+        if options[:videothumb] == true
+          request.add_element('videothumb').add_text('1')
+        end
         if options.has_key?(:custom_thumbnail)
           request.add_element('customThumbnail', 
             'width' => options[:custom_thumbnail][:width].to_s, 
@@ -54,10 +91,15 @@ module Simplificator
         root
       end
       
+      def build_credits_xml()
+        root = build_root_node()
+        root.add_element('credits')
+        root
+      end
+      
       def validate_thumbnail_options(options)
         raise WebthumbException.new('Need an URL') if options[:url] == nil || options[:url] == ''
-        raise WebthumbException.new("output_type is invalid: #{options[:output_type]}") if options.has_key?(:output_type) and (not Base::VALID_OUTPUT_TYPES.include?(options[:output_type]))
-        
+        #raise WebthumbException.new("output_type is invalid: #{options[:output_type]}") if options.has_key?(:output_type) and (not Base::VALID_OUTPUT_TYPES.include?(options[:output_type]))
       end
     end
 

data/test/webthumb_test.rb

@@ -4,8 +4,28 @@ class WebthumbTest < Test::Unit::TestCase
   
   
   def test_build_fetch()
-    xml = Webthumb.new('1234').send(:build_thumbnail_xml, :url => 'http://simplificator.com')
+    xml = Webthumb.new('1234').send(:build_thumbnail_xml, 
+      :url => 'http://simplificator.com', 
+      :videothumb => true, :fullthumb => true, :effect => 'dropshadow', :output_type => :jpg, 
+      :width => 1024, :height => 2048, :custom_thumbnail => {:width => 300, :height => 400},
+      :excerpt => {:x => 30, :y => 40, :width => 600, :height => 345}, :delay => 20, :notify => 'http://foo.bar.com')
     assert_equal('http://simplificator.com', REXML::XPath.first(xml, 'request/url').text)
+    assert_equal('1', REXML::XPath.first(xml, 'request/videothumb').text)
+    assert_equal('1', REXML::XPath.first(xml, 'request/fullthumb').text)
+    assert_equal('dropshadow', REXML::XPath.first(xml, 'request/effect').text)
+    assert_equal('jpg', REXML::XPath.first(xml, 'request/outputType').text)
+    assert_equal('1024', REXML::XPath.first(xml, 'request/width').text)
+    assert_equal('2048', REXML::XPath.first(xml, 'request/height').text)
+    assert_equal('300', REXML::XPath.first(xml, 'request/customThumbnail').attributes['width'])
+    assert_equal('400', REXML::XPath.first(xml, 'request/customThumbnail').attributes['height'])
+    assert_equal('30', REXML::XPath.first(xml, 'request/excerpt/x').text)
+    assert_equal('40', REXML::XPath.first(xml, 'request/excerpt/y').text)
+    assert_equal('600', REXML::XPath.first(xml, 'request/excerpt/width').text)
+    assert_equal('345', REXML::XPath.first(xml, 'request/excerpt/height').text)
+    assert_equal('20', REXML::XPath.first(xml, 'request/delay').text)
+    assert_equal('http://foo.bar.com', REXML::XPath.first(xml, 'request/notify').text)
+    
+    
   end
 
   def test_build_job_status_xml()

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: simplificator-rwebthumb
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors: 
 - Simplificator GmbH
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-10 00:00:00 -07:00
+date: 2008-07-11 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -29,7 +29,6 @@ files:
 - test/base_test.rb
 - test/helper.rb
 - test/job_test.rb
-- test/run_test.rb
 - test/webthumb_test.rb
 - README
 - init.rb