turkee 1.2.2 → 2.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,27 @@
+## MAC OS
+.DS_Store
+
+*.gem
+build.sh
+
+## TEXTMATE
+*.tmproj
+tmtags
+*.log
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+.idea
+
+## PROJECT::SPECIFIC

data/Gemfile.lock

@@ -0,0 +1,124 @@
+PATH
+  remote: .
+  specs:
+    turkee (2.0.0)
+      lockfile
+      rails (>= 3.1.1)
+      rturk (>= 2.4.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.2.3)
+      actionpack (= 3.2.3)
+      mail (~> 2.4.4)
+    actionpack (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.1)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
+    activemodel (3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+    activerecord (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+    activesupport (3.2.3)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    diff-lcs (1.2.3)
+    erubis (2.7.0)
+    factory_girl (3.2.0)
+      activesupport (>= 3.0.0)
+    hike (1.2.2)
+    i18n (0.6.0)
+    journey (1.0.4)
+    json (1.7.7)
+    lockfile (2.1.0)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    metaclass (0.0.1)
+    mime-types (1.22)
+    mocha (0.11.4)
+      metaclass (~> 0.0.1)
+    multi_json (1.3.4)
+    nokogiri (1.5.9)
+    polyglot (0.3.3)
+    rack (1.4.5)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.3)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (3.2.3)
+      actionmailer (= 3.2.3)
+      actionpack (= 3.2.3)
+      activerecord (= 3.2.3)
+      activeresource (= 3.2.3)
+      activesupport (= 3.2.3)
+      bundler (~> 1.0)
+      railties (= 3.2.3)
+    railties (3.2.3)
+      actionpack (= 3.2.3)
+      activesupport (= 3.2.3)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (10.0.4)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    rspec-rails (2.13.0)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rturk (2.10.1)
+      nokogiri (>= 1.4.1)
+      rest-client (>= 1.4.0)
+    spork (0.9.2)
+    sprockets (2.1.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
+    thor (0.14.6)
+    tilt (1.3.7)
+    treetop (1.4.12)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.37)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  factory_girl (>= 1.3.2)
+  mocha
+  rspec-rails (~> 2.6)
+  spork
+  sqlite3
+  turkee!

data/Guardfile

@@ -0,0 +1,12 @@
+guard 'spork', :rspec_env => { 'RAILS_ENV' => 'test' } do
+  watch('spec/spec_helper.rb')
+end
+
+
+guard 'rspec', :version => 2, :cli => "--drb" do
+  watch(%r{^spec/.+_spec\.rb$})
+
+  # lib/
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+end
+

data/README.rdoc

@@ -1,18 +1,21 @@
-== Turkee Description
+== WHAT TURKEE CAN DO
 
-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.
+* Perform user feedback studies easily.
+http://i.imgur.com/wIU40BAl.png
+
+* Seamlessly convert your Rails forms for use on Mechanical Turk.
+* Easily import the data posted by the Mechanical Turk workers back into your data models.
 
 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.
 
 
-== Install/Upgrade
+== INSTALL/UPGRADE
 
 Add turkee to your Gemfile as a gem dependency, then do a 'bundle install':
 
     gem 'turkee'
 
 
-
 If you're upgrading Turkee (1.1.1 and prior) or installing for the first time, run:
 
     rails g turkee --skip
@@ -29,9 +32,9 @@ If you haven't created a Mechanical Turk account, surf on over to {Amazon's Web
 Once you have your account created, you can access your AWS access key and secret access key from {here.}[https://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key]
 
 
-== Configuration
+== CONFIGURATION
 
-Inside the config/initializers directory, you'll see the file turkee.rb.  Edit that file with your Amazon credenti.
+Inside the config/initializers directory, you'll see the file turkee.rb.  Edit the file with your Amazon credentials.
 
     AWSACCESSKEYID      = 'XXXXXXXXXXXXXXXXXX'
     AWSSECRETACCESSKEY  = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYY'
@@ -39,14 +42,13 @@ Inside the config/initializers directory, you'll see the file turkee.rb.  Edit t
     RTurk::logger.level     = Logger::DEBUG
     RTurk.setup(AWSACCESSKEYID, AWSSECRETACCESSKEY, :sandbox => (Rails.env == 'production' ? false : true))
 
-
-== Use
-
-1) Run your migrations :
+Run the 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:
+== BASIC FORMS
+
+1) 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
@@ -60,7 +62,7 @@ Inside the config/initializers directory, you'll see the file turkee.rb.  Edit t
             @survey        = Survey.new
         end
 
-3) Change your forms to use the form helper.
+2) Change your forms to use the form helper.
 
     <%= turkee_form_for(@survey, params) do |f| %>
         <p><%= f.text_area :value, :disabled => @disabled %></p>
@@ -69,7 +71,8 @@ Inside the config/initializers directory, you'll see the file turkee.rb.  Edit t
 
 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 :
+
+3) Run the following rake task to post to Mechanical Turk :
     # Host URL of your application
     # Title of your HIT
     # Description of your HIT
@@ -88,9 +91,28 @@ This will insert a row for the requested HIT into the turkee_tasks table.  The t
 
 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
 
-5) Allow some time for the Mechanical Turk workers ("Turkers") to respond to your HIT.
+== USER FEEDBACK STUDIES
+
+1) Add the following method call to your app/views/layouts/application.html.haml file :
+
+    <%= turkee_study %>
+
+2) Call the create_study rake task :
+
+    rake turkee:create_study[<Application Page URL>, <HIT Title>, <HIT Description>, <Number of Assignments>, <Reward>, <Lifetime of HIT>]
+
+    # 30 Assignments at a quarter each requesting feedback on my site
+    RAILS_ENV=production rake turkee:create_study['https://yoursite.com/page-to-be-test',"Can you help me test my website?","Give feedback below on what you didn't like about my site. Click submit below when you're finished.", 30,0.25, 20]
 
-6) Run the rake task that retrieves the values from Mechanical Turk and stores the user entered values into your model.
+3) The Turker will see a feedback form overlayed over your website.  Within this textarea, they can provide feedback.
+
+Screenshot:
+
+http://i.imgur.com/wIU40BA.png
+
+== RETRIEVING RESULTS
+
+1) Run the rake task that retrieves the values from Mechanical Turk and stores the user entered values into your model.
     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.
@@ -104,7 +126,10 @@ 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.
+
+== DATA RETRIEVAL; THE INS AND OUTS
+
+1) 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. :
     class Survey < ActiveRecord::Base
       def approve?
@@ -112,14 +137,14 @@ As for Mechanical Turk approval, if the row is created and you haven't specified
       end
     end
 
-8) When all specified assignments for a HIT have been completed, Turkee will attempt to call the optional hit_complete class method for the model.  This can be used for any cleanup logic.  E.g. :
+2) When all specified assignments for a HIT have been completed, Turkee will attempt to call the optional hit_complete class method for the model.  This can be used for any cleanup logic.  E.g. :
     class Survey < ActiveRecord::Base
       def self.hit_complete(turkee_task)
         #do something
       end
     end
 
-9) If all of specified assignments for a HIT have not been completed by the end of the HITs lifetime, Turkee will attempt to call the optional hit_expired class method for the model.  This can be used for any cleanup logic.  E.g. :
+3) If all of specified assignments for a HIT have not been completed by the end of the HITs lifetime, Turkee will attempt to call the optional hit_expired class method for the model.  This can be used for any cleanup logic.  E.g. :
     class Survey < ActiveRecord::Base
       def self.hit_expired(turkee_task)
         #do something
@@ -132,16 +157,23 @@ As for Mechanical Turk approval, if the row is created and you haven't specified
 1) You can use the params hash to pass object IDs to your forms.  E.g. if you wanted to setup a form of questions about a given URL (let's call the model UrlSurvey), your code would look something like :
 
     URL.all do |url|
-        Turkee::TurkeeTask.create_hit(host, hit_title, hit_description, UrlSurvey, num_assignments, reward,
+        Turkee::TurkeeTask.create_hit(host, "Enter the address displayed for the given url.",
+            hit_description, UrlSurvey, num_assignments, reward,
             lifetime, duration, {}, {:url_id => url.id}, {})
     end
 
 Then when displaying your form, you can find the URL object via the params[:url_id] value.
 
+2) You can pass in qualifications to allow only certain Turkers to work on your HIT.
 
-2) Turkee assumes that the form url will be the new action for the class passed to create_hit.  If you have a more complex form url which would be the case for nested resources, you can use the :form_url
-option to designate a form url different from the default.
+E.g. qualifications = {:approval_rate => {:gt => 70}, :country => {:eql => 'US'}}
+
+    Turkee::TurkeeTask.create_hit(host, hit_title, hit_description, UrlSurvey, num_assignments, reward, lifetime, duration, qualifications, {}, {})
 
+* The rake task does not support the passing of qualifications.
+
+3) Turkee assumes that the form url will be the new action for the class passed to create_hit.  If you have a more complex form url which would be the case for nested resources, you can use the :form_url
+option to designate a form url different from the default.
 
     form_url = Rails.application.routes.url_helpers.send("new_user_survey_path",@my_survey)
 

data/VERSION

@@ -0,0 +1 @@
+2.0.0

data/lib/generators/turkee/templates/create_turkee_study.rb.erb

@@ -0,0 +1,18 @@
+class CreateTurkeeStudy < ActiveRecord::Migration
+
+    def self.up
+        create_table "turkee_studies" do |t|
+            t.integer "turkee_task_id"
+            t.text "feedback"
+            t.string "gold_response"
+            t.timestamps
+        end
+
+        add_index :turkee_studies, :turkee_task_id
+    end
+
+    def self.down
+        drop_table :turkee_studies
+    end
+
+end

data/lib/generators/turkee/turkee_generator.rb

@@ -38,6 +38,10 @@ class TurkeeGenerator < Rails::Generators::Base
 
     migration_template "add_expired.rb.erb", "db/migrate/add_expired.rb"
 
+    sleep 1
+
+    migration_template "create_turkee_study.rb.erb", "db/migrate/create_turkee_study.rb"
+
   end
 
   def create_initializer

data/lib/helpers/turkee_forms_helper.rb

@@ -0,0 +1,68 @@
+module Turkee
+
+  module TurkeeFormHelper
+    def turkee_form_for(record, params, options = {}, &proc)
+      raise ArgumentError, "turkee_form_for now requires that you pass in the entire params hash, instead of just the assignmentId value. " unless params.is_a?(Hash)
+
+      options.merge!({:url => mturk_url})
+
+      buffer = ''
+      form_for record, options do |f|
+        params.each do |k,v|
+          unless ['action','controller'].include?(k) || !v.is_a?(String)
+            buffer << hidden_field_tag(k, v)
+            cookies[k] = v
+          end
+        end
+
+        ['assignmentId', 'workerId', 'hitId'].each do |k|
+          buffer << hidden_field_tag(k, cookies[k]) if !params.has_key?(k) && cookies.has_key?(k)
+        end
+
+        buffer << yield(f)
+        buffer.html_safe
+      end
+    end
+
+    def turkee_study(id = nil)
+      task     = id.nil? ? Turkee::TurkeeTask.last : Turkee::TurkeeTask.find(id)
+      study    = Turkee::TurkeeStudy.new
+      disabled = Turkee::TurkeeFormHelper::disable_form_fields?(params[:assignmentId])
+
+      if task.present?
+        style =  "position: fixed; top: 120px; right: 30px; color: #FFF;"
+        style << "width: 400px; height: 375px; z-index: 100; padding: 10px;"
+        style << "background-color: rgba(0,0,0, 0.5); border: 1px solid #000;"
+        div_for(task, :style => style) do
+          content = content_tag(:h3, "DIRECTIONS", :style => 'text-align: right; color:#FF0000;')
+          content << task.hit_description.html_safe
+          content << '<hr/>'.html_safe
+          content << turkee_form_for(study, params) do |f|
+            buffer =  f.label(:feedback, "Feedback?:")
+            buffer <<  f.text_area(:feedback, :rows => 3, :disabled => disabled)
+            buffer << f.label(:gold_response, "Enter the fourth word from your above feedback :")
+            buffer << f.text_field(:gold_response, :disabled => disabled)
+            buffer << f.hidden_field(:turkee_task_id, :value => task.id)
+            buffer << '<br/>'.html_safe
+            buffer << f.submit('Submit', :disabled => disabled)
+            buffer
+          end.html_safe
+          content
+        end
+      end
+    end
+
+    # Returns the external Mechanical Turk url used to post form data based on whether RTurk is cofigured
+    #   for sandbox use or not.
+    def mturk_url
+      RTurk.sandbox? ? "https://workersandbox.mturk.com/mturk/externalSubmit" : "https://www.mturk.com/mturk/externalSubmit"
+    end
+
+    # Returns whether the form fields should be disabled or not (based on the assignment_id)
+    def self.disable_form_fields?(assignment)
+      assignment_id = assignment.is_a?(Hash) ? assignment[:assignmentId] : assignment
+      (assignment_id.nil? || assignment_id == 'ASSIGNMENT_ID_NOT_AVAILABLE')
+    end
+  end
+
+end

data/lib/models/turkee_imported_assignment.rb

@@ -0,0 +1,15 @@
+require 'active_record'
+
+module Turkee
+  class TurkeeImportedAssignment < ActiveRecord::Base
+    attr_accessible :assignment_id, :turkee_task_id, :worker_id, :result_id
+
+    def self.record_imported_assignment(assignment, result, turk)
+      TurkeeImportedAssignment.create!(:assignment_id => assignment.id,
+                                       :turkee_task_id => turk.id,
+                                       :worker_id => assignment.worker_id,
+                                       :result_id => result.id)
+    end
+
+  end
+end