shared_workforce 0.2.12 → 0.2.13

data/README.markdown

@@ -27,121 +27,168 @@ Register for a beta invitation at [sharedworkforce.com](http://www.sharedworkfor
   
 Add shared_workforce to your Gemfile:
 
-    gem "shared_workforce"
+```ruby
+gem "shared_workforce"
+```
 
 Create config/initializers/shared_workforce.rb
 
-    SharedWorkforce.configure do |config|
-      config.api_key = "your-api-key"
-      config.callback_host = "http://your-website-host"
-    end
+```ruby
+SharedWorkforce.configure do |config|
+  config.api_key = "your-api-key"
+  config.callback_host = "http://your-website-host"
+end
+```
 
 If you're not using Rails, simply require the gem or include it in your Gemfile, set the client configuration settings as above.
 
 ### Step 3 - define tasks
 
-If, for example, you would like to approve a photo on upload, create your first task in a file called app/tasks/approve_photo.rb   
-    
-    class ApprovePhotoTask
-      include SharedWorkforce::Task
-
-      title 'Approve Photo'
+A class defines the content (for example, an image url) and instructions that the human worker will see when they work on your task, and the methods to be run once the task has been completed.
 
-      instruction 'Look at this photo. Please tick all that apply.'
-      responses_required 1
+If, for example, you would like to approve a photo on upload, create a task class file in an `app/tasks` directory (or anywhere in the load path).
 
-      answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
-      answer_type :tags
-      image_url "http://www.google.com/logo.png"
 
-      on_success :moderate_photo
+`app/tasks/tag_photo_task.rb`:
 
-      def moderate_photo(photo, responses)
-        if responses.map { |r| r[:answer] }.include?('Offensive')
-          photo.hide!
-          photo.add_comment("Photo is offensive")
-        end
-        puts "Photo Moderated"
-      end
-      
+```ruby
+class TagPhotoTask
+  include SharedWorkforce::Task
+  
+  title 'Please tag our photo'
+  
+  instruction 'Please look at the photo and tick all that apply.'
+  
+  answer_type :tags
+  answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
+  
+  responses_required 1
+  
+  on_success :moderate_photo
+  
+  def setup(photo)
+    self.image_url = photo.url
+  end
+  
+  def moderate_photo(photo, responses)
+    # responses => [{:answer=>['Offensive', 'Contains Nudity']}]
+    if responses.map {|r| r[:answer]}.flatten.include?('Offensive')
+      photo.delete
+      photo.user.quarantine("Uploded offensive photo")
     end
-    
+  end
+end
+```
+_**Note:** the task definition includes a `setup` method which is called automatically whenever the task is initialized. In the example, the task's `image_url` (the image shown to the worker) is set from the photo model's url attribute. Any of the task's attributes can be set this way._
+
+Once you have created a task definition, you can request real human responses for a model instance by calling its `create` method. This can be done in an `after_create` callback in one of your Active Record models. This will be covered in more detail in the next section.
 
 ### Step 4 - request tasks
 
-Publishing tasks is simply a case of calling `TaskClass.create()`.  If you are using Rails, this could be done in an after save callback on a model:
+When you publish a task it will be queued for a human worker to complete. You can publish a task in an `after_create` callback on a typical Active Record model:
 
-    class Photo < ActiveRecord::Base
-    
-      after_create :approve_photo
-    
-      def approve_photo
-        ApprovePhotoTask.create(self)
-      end
-    end
+```ruby
+class Photo < ActiveRecord::Base
+  
+  after_create :request_tags
+  
+  def request_tags
+    TagPhotoTask.create(self)
+  end
+end
+```
+
+_**Note:** In the example, the photo model instance (self) is used an argument to the TagPhotoTask.create method. This argument will be available in the setup method and the callback method as shown in the example of a Task Definition in step 3._
+
+When the response(s) from the human workers are collected, the method specified in the `on_success` attribute in your task definition will be called. Typically this will take about 15 minutes. You can check the [Shared Workforce web site](http://www.sharedworkforce.com) for an up to date status on the current response time.
 
+### Unit testing
+
+You can test your task definition by calling its methods directly.
+
+```ruby
+it "should quarantine the user" do
+  photo = Factory(:photo)
+  task = ClassifyPhotoTask.new(photo)
+  task.moderate_photo(photo, [{:answer=>['Offensive']}])
+  photo.user.should be_quarantined
+end
+```
 
 Advanced definition options
 ----------------------------------------
 
 ### Task types
 
-SharedWorkforce currently supports 3 types of task. `:tags` (multiple select), `:choice` (single answer from a list of options), or `:edit` (edit text).
+SharedWorkforce currently supports 5 types of task. Possible options are:
+
+  * `"choice"`: choose one option from a list
+  * `"tags"`: choose any number of options from a list
+  * `"edit"`: edit the text in the 'text' attribute
+  * `"crop"`: crop the photo (see image_crop_ratio)
+  * `"rotate"`: rotate the photo
 
-###Multiple responses
+### Multiple responses
 
 SharedWorkforce supports multiple responses for each task. The callback method provides you with an array of responses from multiple workers. You can create your own logic to decide what to do. This is useful if you want to prevent destructive action unless a number of workers agree.
 
-    class ApprovePhotoTask
-      include SharedWorkforce::Task
+```ruby
+class ApprovePhotoTask
+  include SharedWorkforce::Task
 
-      title 'Approve Photo'
+  title 'Approve Photo'
 
-      instruction 'Look at this photo. Please tick all that apply.'
-      responses_required 3
+  instruction 'Look at this photo. Please tick all that apply.'
+  responses_required 3
 
-      answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
-      answer_type :tags
+  answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
+  answer_type :tags
 
-      on_complete :moderate_photo
+  on_complete :moderate_photo
 
-      def moderate_photo(photo, responses)
-        photo.hide! if responses.map { |r| r[:answer] }.all? { |a| a.include?('Contains Nudity') }
-      end
+  def moderate_photo(photo, responses)
+    photo.hide! if responses.map { |r| r[:answer] }.all? { |a| a.include?('Contains Nudity') }
+  end
 
-    end
-    
+end
+```
 
-###Replacing tasks
+### Replacing tasks
 
 The "replace" option allows you to overwrite or update any existing tasks with the same name and callback params. This could be useful in the example to handle the situation where a user re-uploads their photo - you may only care about the latest one.
 
-    class ApprovePhotoTask
-      include SharedWorkforce::Task
-      ...
-      replace true
-      ...  
-    end
+```ruby
+class ApprovePhotoTask
+  include SharedWorkforce::Task
+  ...
+  replace true
+  ...  
+end
+```
 
-###Cancelling tasks
+### Cancelling tasks
 
 You can cancel tasks when they are no longer relevant.
- 
-    class Photo
-      after_destroy :cancel_tagging_request
 
-      def cancel_tagging_request
-        ApprovePhotoTask.cancel(self)
-      end
-    end
+```ruby 
+class Photo
+  after_destroy :cancel_tagging_request
 
-###Testing and development
+  def cancel_tagging_request
+    ApprovePhotoTask.cancel(self)
+  end
+end
+```
 
-You can black-hole requests to SharedWorkforce for testing and development by adding the following configuration option in your initializer:
+### Disabling requests during development
 
-    SharedWorkforce.configure do |config|
-      config.request_class = SharedWorkforce::TaskRequest::BlackHole
-    end
+You can black-hole requests to Shared Workforce for testing and development by adding the following configuration option in your initializer:
+
+```ruby
+SharedWorkforce.configure do |config|
+  config.request_class = SharedWorkforce::TaskRequest::BlackHole
+end
+```
 
 License
 -----------

data/lib/shared_workforce.rb

@@ -14,6 +14,7 @@ require 'shared_workforce/response_poller'
 require 'shared_workforce/frameworks/rails' if defined?(Rails)
 require 'active_support/inflector'
 require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/object/blank'
 
 module SharedWorkforce
     

data/lib/shared_workforce/configuration.rb

@@ -34,6 +34,10 @@ module SharedWorkforce
       @logger ||= (rails_logger || default_logger)
     end
 
+    def valid?
+      @api_key.present?
+    end
+
     private
 
     def default_request_class

data/lib/shared_workforce/frameworks/rails.rb

@@ -2,10 +2,16 @@ if defined?(ActionController::Metal)
   class Railtie < Rails::Railtie
     initializer 'shared_workforce' do |app|      
       app.config.middleware.use SharedWorkforce::EndPoint
-      if Rails.env.development?
-      	# Stop log buffering when using Foreman in development
-        $stdout.sync = true
-        SharedWorkforce::ResponsePoller.start
+      app.config.after_initialize do
+        if Rails.env.development?
+        	if SharedWorkforce.configuration.valid?
+            # Stop log buffering when using Foreman in development
+            $stdout.sync = true
+            SharedWorkforce::ResponsePoller.start
+          else
+            puts 'Shared Workforce: API key not configured.'
+          end
+        end
       end
     end
   end

data/lib/shared_workforce/version.rb

@@ -1,4 +1,4 @@
 module SharedWorkforce
-  VERSION = "0.2.12"
+  VERSION = "0.2.13"
 
 end

data/spec/configuration_spec.rb

@@ -69,5 +69,12 @@ describe "Configuration" do
 			configuration.logger.should == logger_double
 		end
 	end
+
+	describe "#valid" do
+		it "should be false if no api key is set" do
+			configuration.api_key = nil
+			configuration.should_not be_valid
+		end
+	end
  
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shared_workforce
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.2.13
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-23 00:00:00.000000000 Z
+date: 2012-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70340575489280 !ruby/object:Gem::Requirement
+  requirement: &70323744943380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70340575489280
+  version_requirements: *70323744943380
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70340575503560 !ruby/object:Gem::Requirement
+  requirement: &70323744942960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70340575503560
+  version_requirements: *70323744942960
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70340575502400 !ruby/object:Gem::Requirement
+  requirement: &70323744942540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70340575502400
+  version_requirements: *70323744942540
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70340575498220 !ruby/object:Gem::Requirement
+  requirement: &70323744942040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 1.2.9
   type: :development
   prerelease: false
-  version_requirements: *70340575498220
+  version_requirements: *70323744942040
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &70340575527180 !ruby/object:Gem::Requirement
+  requirement: &70323744941620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70340575527180
+  version_requirements: *70323744941620
 description: Shared Workforce is a service and simple API for human intelligence tasks
 email:
 - sam@samoliver.com