turkee 1.0.1 → 1.0.2

data/README.rdoc

@@ -1,16 +1,12 @@
-== Description
+== Turkee Description
 
-Turkee simplifies the process of posting and retrieving HIT (Human Intelligence Task) data from Amazon's Mechanical Turk.
+Seamlessly convert your Rails forms for use on Mechanical Turk.  Then, easily import the data posted by the Mechanical Turk workers back into your data models.
 
-Forms are created using a simple form helper.  HITs are created by issuing a rake command.  Retrieving form data from Amazon requires just one more rake command.
+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.
 
 == Dependencies
 
-Make sure that the rturk gem is installed, referenced in your environment.rb :
-
-    config.gem 'rturk'
-
-...and configured with your Amazon Turk credentials. I created a config/initializers/turk_task_config.rb file with the following in it:
+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:
 
     TURKTASK_AWSACCESSKEYID = 'XXXXXXXXXXXXXXXXXX'
     TURKTASK_AWSACCESSKEY   = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYY'
@@ -31,25 +27,38 @@ And add it to your environment.rb configuration as a gem dependency:
 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 javascript file and migrations into your application:
+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.
 
 == Use
 
-1) Add 'turkee' to your javascript includes in your application.html.erb
-    <%= javascript_include_tag :defaults, :turkee %>
-   * Turkee requires the default Rails javascript libraries, so be sure you are including those as well (as show above with :defaults).
-2) Run your migrations :
+1) Run your migrations :
 
     rake db:migrate
 
+2) You should disable form controls if the Turker hasn't accepted the HIT.  You can determine this from your controller:
+    class SurveysController < ApplicationController
+
+        def new
+            @assignment_id = params[:assignmentId]
+            @disabled      = Turkee::TurkeeFormHelper::disable_form_fields?(@assignment_id)
+
+            # If you wanted to find the associated turkee_task, you could do a find by hitId
+            #  Not necessary in a simple example.
+            # @turkee_task   = Turkee::TurkeeTask.find_by_hit_id(params[:hitId]).id rescue nil
+
+            ...
+            @survey        = Survey.new
+        end
+
 3) Change your forms to use the form helper.
-    <% turkee_form_for @user do |form| %>
-        <%= form.inputs %>
-        <%= form.buttons %>
+    <% turkee_form_for(@survey, @assignment_id) do |f| %>
+        <p><%= f.text_area :value, :disabled => @disabled %></p>
+        <p><%= f.submit 'Create', :disabled => @disabled %></p>
     <% end %>
+
 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 :
@@ -65,7 +74,9 @@ Using the turkee_form_for helper will post the form to the Mechanical Turk sandb
     e.g. :
     rake turkee:posthit ["Please complete our survey", "Tell us your favorite color.", "Survey", 100, 0.05, 2]
 
-5) Allow some time for the "Turkers" to respond to your HIT.
+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).
+
+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
@@ -77,6 +88,9 @@ Rerun this task periodically to retrieve newly entered form values.  You can set
     # E.g. run every five minutes
     */5 * * * * cd /var/www/your/turk/application && rake turkee:getresults
 
+Or you can directly call :
+
+    Turkee::TurkeeTask.process_hits
 
 7) When a response is retrieved from Mechanical Turk, Turkee attempts to create a data row for the model specified using the corresponding retrieved data.  If the row cannot be created (input failed model validations), the assignment is rejected.
 As for Mechanical Turk approval, if the row is created and you haven't specified your own custom approve? method for the model, the assignment will automatically be approved. If you'd like to add your own custom approval method, add the approve? instance method to your model.  E.g. :

data/generators/turkee/turkee_generator.rb

@@ -2,8 +2,6 @@ class TurkeeGenerator < Rails::Generator::Base
 
   def manifest
     record do |m|
-      m.directory File.join('public', 'javascripts')
-      m.template 'turkee.js', File.join('public', 'javascripts', 'turkee.js')
       m.migration_template "turkee_migration.rb.erb", File.join('db', 'migrate'), :migration_file_name => 'create_turkee_tasks'
       m.sleep 1   # Need this sleep so that we don't get the same migration timestamp for both migrations
       m.migration_template "turkee_imported_assignments.rb.erb", File.join('db', 'migrate'), :migration_file_name => 'create_turkee_imported_assignments'
@@ -11,7 +9,7 @@ class TurkeeGenerator < Rails::Generator::Base
   end
 
   def banner
-    %{Usage: #{$0} #{spec.name}\nCopies turkee.js to public/javascripts/ and generates needed migrations.}
+    %{Usage: #{$0} #{spec.name}\nCopies needed migrations to project.}
   end
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: turkee
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Jim Jones
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-14 00:00:00 -07:00
+date: 2010-10-19 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,7 +77,6 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - Rakefile
-- generators/turkee/templates/turkee.js
 - generators/turkee/templates/turkee_imported_assignments.rb.erb
 - generators/turkee/templates/turkee_migration.rb.erb
 - generators/turkee/turkee_generator.rb

data/generators/turkee/templates/turkee.js

@@ -1,45 +0,0 @@
-// Javascript referenced from the rturk example.
-
-// Initializes a mechanical turk form and disables the form button
-//   until the user has accepted the turk task.
-
-function gup( name )
-{
-  var regexS = "[\\?&]"+name+"=([^&#]*)";
-  var regex = new RegExp( regexS );
-  var tmpURL = window.location.href;
-  var results = regex.exec( tmpURL );
-  if( results == null )
-    return "";
-  else
-    return results[1];
-}
-
-//
-// This method decodes the query parameters that were URL-encoded
-//
-function decode(strToDecode)
-{
-  var encoded = strToDecode;
-  return unescape(encoded.replace(/\+/g, " "));
-}
-
-function mturk_form_init(obj_name)
-{
-    document.getElementById('assignmentId').value = gup('assignmentId');
-
-    //
-    // Check if the worker is PREVIEWING the HIT or if they've ACCEPTED the HIT
-    //
-    if (gup('assignmentId') == "ASSIGNMENT_ID_NOT_AVAILABLE")
-    {
-      // If we're previewing, disable the button and give it a helpful message
-      document.getElementById(obj_name + '_submit').disabled = true;
-      document.getElementById(obj_name + '_submit').value = "You must ACCEPT the HIT before you can submit the results.";
-    } else {
-        var form = document.getElementById('mturk_form');
-        if (document.referrer && ( document.referrer.indexOf('workersandbox') != -1) ) {
-            form.action = "https://workersandbox.mturk.com/mturk/externalSubmit";
-        }
-    }
-}