turkee 1.0.2 → 1.0.3

data/README.rdoc

@@ -4,6 +4,10 @@ Seamlessly convert your Rails forms for use on Mechanical Turk.  Then, easily im
 
 External forms are created using a simple form helper.  HITs are created by issuing a rake command.  Retrieving submitted response data and importing that data into your model(s) requires just one more rake command.
 
+== Examples
+
+If you'd like to jump straight into code, check out the {Turkee Iterator}[https://github.com/aantix/Turkee-Iterator] example.
+
 == Dependencies
 
 Make sure that the rturk gem is installed configured with your Amazon Turk credentials. I created a config/initializers/turk_task_config.rb file with the following in it:
@@ -20,17 +24,21 @@ Install the Turkee gem:
 
     sudo gem install turkee
 
-And add it to your environment.rb configuration as a gem dependency:
+For Rails 2, add it to your environment.rb configuration as a gem dependency:
 
     config.gem 'turkee'
 
+For Rails 3, add it to your Gemfile as a gem dependency, then do a 'bundle install':
+
+    gem 'turkee'
+
 To access the Turkee rake tasks, add the following to your application's Rakefile:
     require 'tasks/turkee'
 
 Run the turkee generator from your application directory to copy the needed migrations into your application:
 
     ./script/generate turkee    # Rails 2
-    ## Support for Rails 3 in the future.
+    rails g turkee              # Rails 3
 
 == Use
 
@@ -62,6 +70,7 @@ Run the turkee generator from your application directory to copy the needed migr
 Using the turkee_form_for helper will post the form to the Mechanical Turk sandbox if you're in development/test mode, otherwise it will be posted to Mechanical Turk production/live site.
 
 4) Run the following rake task to post to Mechanical Turk :
+    # Host URL of your application
     # Title of your HIT
     # Description of your HIT
     # Model name of your task form (the New action should be implemented)
@@ -69,24 +78,29 @@ Using the turkee_form_for helper will post the form to the Mechanical Turk sandb
     # The reward for a successful completion
     # The lifetime of the HIT in days (e.g. 5 days)
 
-    rake turkee:posthit[<Title>, <Description>, <Model>, <Number of Assignments>, <Reward>, <Lifetime>]
+    rake turkee:post_hit[<Host>, <Title>, <Description>, <Model>, <Number of Assignments>, <Reward>, <Lifetime>]
 
     e.g. :
-    rake turkee:posthit ["Please complete our survey", "Tell us your favorite color.", "Survey", 100, 0.05, 2]
+    rake turkee:post_hit["https://www.yourapp.com","Please complete our survey","Tell us your favorite color.","Survey",100,0.05,2]
+    ** Do not put spaces before or after commas for the rake task parameters
+
+This will insert a row for the requested HIT into the turkee_tasks table.  The turkee_tasks entry stores (along with the other properties) the HIT URL (e.g. http://workersandbox.mturk.com/mturk/preview?groupId=1HGHJJGHQSJB7WMWJ33YS8WM169XNIL ) and HIT ID (e.g. 1J1EXO8SUQ3URTTUYGHJ7EKUT11 ).  These values are returned from Mechanical Turk when the HIT request is posted.
+
+When a Turk worker views your HIT, the HIT will display your form within an iFrame.  With the above example, Mechanical Turk will open an iFrame for the HIT assignment displaying the form http://www.yourapp.com/surveys/new
 
-This will insert a row for the requested HIT into the turkee_tasks table.  The turkee_tasks entry stores (among other things) the HIT URL and HIT ID (as returned from the Mechanical Turk API call).
+** The application that hosts your external forms preferably should have an https interface (you're going to have to buy an SSL certificate).  If the forms are hosted on an unsecured host (http), because Mechanical Turk defaults to https, you're going to receive the ugly popup from IE regarding "mixed content" (http://msdn.microsoft.com/en-us/library/ee264315%28v=vs.85%29.aspx).
 
 5) Allow some time for the Mechanical Turk workers ("Turkers") to respond to your HIT.
 
 6) Run the rake task that retrieves the values from Mechanical Turk and stores the user entered values into your model.
-    rake turkee::getresults
+    rake turkee::get_all_results
 
 Rerun this task periodically to retrieve newly entered form values.  You can setup this task as a cronjob to automate this.
 
     crontab -e
 
     # E.g. run every five minutes
-    */5 * * * * cd /var/www/your/turk/application && rake turkee:getresults
+    */5 * * * * cd /var/www/your/turk/application && rake turkee:get_all_results
 
 Or you can directly call :
 
@@ -102,4 +116,4 @@ As for Mechanical Turk approval, if the row is created and you haven't specified
 
 == Copyright
 
-Copyright (c) 2010 Jim Jones. See LICENSE for details.
+Copyright (c) 2010 - 2011 Jim Jones. See LICENSE for details.

data/Rakefile

@@ -23,7 +23,6 @@ begin
     gem.email = "jjones@aantix.com"
     gem.homepage = "http://github.com/aantix/turkee"
     gem.authors = ["Jim Jones"]
-    gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "rturk", ">= 2.3.0"
     gem.add_development_dependency "lockfile", ">= 1.4.3"
     gem.post_install_message = INSTALL_MESSAGE

data/lib/tasks/turkee.rb

@@ -1,3 +1,4 @@
+require 'rake'
 require 'turkee'
 
 include ActionController::PolymorphicRoutes
@@ -6,10 +7,11 @@ include ActionView::Helpers::UrlHelper
 # clear && rake turkee:post_hit['Test title','Test desc','Joke',3,0.05,1] --trace
 
 namespace :turkee do
-  desc "Post your form to Mechanical Turk (HIT). Task takes HIT title, HIT description, model name, number of responses, reward for each response, and number of days the HIT should be valid."
-  task :post_hit, :title, :description, :model, :num_assignments, :reward, :lifetime, :needs => :environment do |t, args|
-    Turkee::TurkeeTask.create_hit(args[:title], args[:description], args[:model],
-                                  args[:num_assignments], args[:reward], args[:lifetime])
+  desc "Post your form to Mechanical Turk (HIT). Task takes the application's host URL, HIT title, HIT description, model name, number of responses, reward for each response, and number of days the HIT should be valid."
+  task :post_hit, :host, :title, :description, :model, :num_assignments, :reward, :lifetime, :needs => :environment do |t, args|
+    hit = Turkee::TurkeeTask.create_hit(args[:host],args[:title], args[:description], args[:model],
+                                        args[:num_assignments], args[:reward], args[:lifetime])
+    puts "Hit created ( #{hit.hit_url} )."
   end
 
   desc "Retrieve all results from Mechanical Turk for all open HITs."

data/lib/turkee.rb

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'socket'
+require 'rturk'
 require 'lockfile'
 require 'active_record'
 require 'action_view'
@@ -40,10 +41,6 @@ module Turkee
               param_hash = Rack::Utils.parse_nested_query(params)
               model      = find_model(param_hash)
 
-              logger.debug "params     = #{params.inspect}"
-              logger.debug "param_hash = #{param_hash.inspect}"
-              logger.debug "model      = #{model.inspect}"
-
               next if model.nil?
 
               result = model.create(param_hash[model.to_s.underscore])
@@ -196,7 +193,7 @@ module Turkee
       end
 
       # concat(form_tag(options.delete(:url) || {}, options.delete(:html) || {}))
-      concat(form_tag(mturk_url))
+      concat(form_tag(mturk_url, options.delete(:html) || {}))
       concat("<input type=\"hidden\" id=\"assignmentId\" name=\"assignmentId\" value=\"#{assignment_id}\"/>")
       fields_for(object_name, *(args << options), &proc)
       concat('</form>'.html_safe)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: turkee
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 1
   - 0
-  - 2
-  version: 1.0.2
+  - 3
+  version: 1.0.3
 platform: ruby
 authors: 
 - Jim Jones
@@ -15,29 +15,13 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-19 00:00:00 -07:00
+date: 2011-02-27 00:00:00 -08:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 13
-        segments: 
-        - 1
-        - 2
-        - 9
-        version: 1.2.9
-  type: :development
-  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rturk
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -49,11 +33,11 @@ dependencies:
         - 0
         version: 2.3.0
   type: :development
-  version_requirements: *id002
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: lockfile
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -65,7 +49,7 @@ dependencies:
         - 3
         version: 1.4.3
   type: :development
-  version_requirements: *id003
+  version_requirements: *id002
 description: Turkee will help you to create your Rails forms, post the HITs, and retrieve the user entered values from Mechanical Turk.
 email: jjones@aantix.com
 executables: []