surveyor 0.6.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+surveys/fixtures/*.yml

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 Brian Chamberlain and Mark Yoon
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# Survey On Rails
+
+Surveyor is a rails (gem) plugin, that brings surveys to your rails app. Before Rails 2.3, it was implemented as a Rails Engine. Surveys are written in a DSL (Domain Specific Language), with examples available in the "kitchen sink" survey.
+
+# Installation
+
+As a plugin:
+
+    sudo gem install haml
+    script/plugin install git://github.com/breakpointer/surveyor.git
+
+Or as a gem plugin:
+  
+  # in environment.rb
+  config.gem "surveyor", :version => '>=0.4.1', :lib => false
+  
+    sudo rake gems:install
+
+Generate assets, run migrations:
+    
+    script/generate surveyor
+    rake db:migrate
+
+Try out the "kitchen sink" survey:
+
+    rake surveyor FILE=surveys/kitchen_sink_survey.rb
+
+# Configuration
+
+The surveyor generator creates config/initializers/surveyor.rb. There, you can specify:
+
+- your own relative root for surveys ('/' is not recommended as any path will be interpreted as a survey name)
+- your own custom title (string) for the survey list page
+- your own custom layout file name, in your app/views/layouts folder
+- your own custom finish url for all surveys. you can give a string (a path), a symbol (the name of a method in ApplicationController)
+- if you would like surveys to require authorization via the restful_authentication plugin
+- if you would like to extend the surveyor_controller (see Extending Surveyor below)
+
+The initializer runs once, when the app starts. The block style is used to keep multiple options DRY (defaults below):
+
+    Surveyor::Config.run do |config|
+      config['default.relative_url_root'] = "surveys/" # should end with '/'
+      config['default.title'] = "You can take these surveys:"
+      config['default.layout'] = "surveyor_default"
+      config['default.finish'] =  "/surveys"
+      config['use_restful_authentication'] = false
+      config['extend_controller'] = false
+    end
+    
+You can update surveyor's at any time. Use the block style (above), or the individual style:
+
+    Surveyor::Config['default.title'] = "Cheese is great!"
+
+To look at the current surveyor configuration:
+    
+    Surveyor::Config.to_hash.inspect
+
+# Extending surveyor
+
+Surveyor's models, helper, and controller can be extended from custom modules your app/models, app/helpers and app/controllers directories. To generate the sample files and sample layout, run:
+
+    script/generate extend_surveyor
+
+Any of surveyor's models class_eval, class methods, and instance methods can be modified. Include the following in config/initializers/surveyor.rb:
+
+    require 'models/survey_extensions' # Extended the survey model
+
+SurveyorHelper class_eval and instance methods can be modified. Include the following in config/initializers/surveyor.rb:
+
+    require 'helpers/surveyor_helper_extensions' # Extend the surveyor helper
+
+SurveyorController class_eval, class methods, instance methods, and actions can be modified. Action methods should be specified separately in the Actions submodule. Set the following option in config/initializers/surveyor.rb Surveyor::Config block:
+
+    config['extend_controller'] = true
+
+# Sample layout
+
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+    <head>
+      <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
+      <title>Survey: <%= controller.action_name %></title>
+      <%= surveyor_includes # calls surveyor_javascripts + surveyor_stylesheets %>
+    </head>
+    <body>
+      <div id="flash"><%= flash[:notice] %></div>
+      <div id="survey_with_menu">
+        <%= yield %>
+      </div>
+    </body>
+    </html>
+  
+The <code>surveyor\_includes</code> helper just calls <code>surveyor\_stylsheets + surveyor\_javascripts</code> which in turn call:
+
+    stylesheet_link_tag 'surveyor/reset', 'surveyor/surveyor', 'surveyor/ui.theme.css','surveyor/jquery-ui-slider-additions'
+
+    javascript_include_tag 'surveyor/jquery-1.2.6.js', 'surveyor/jquery-ui-personalized-1.5.3.js', 'surveyor/accessibleUISlider.jQuery.js','surveyor/jquery.form.js', 'surveyor/surveyor.js'
+    
+# Dependencices
+
+Surveyor depends on Rails 2.3 and the SASS style sheet language, part of HAML (http://haml.hamptoncatlin.com/download)
+
+Copyright (c) 2008-2009 Brian Chamberlain and Mark Yoon, released under the MIT license

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "surveyor"
+    gem.summary = %Q{A rails (gem) plugin to enable surveys in your application}
+    gem.email = "yoon@northwestern.edu"
+    gem.homepage = "http://github.com/breakpointer/surveyor"
+    gem.authors = ["Brian Chamberlain", "Mark Yoon"]
+    gem.add_dependency 'haml'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "surveyor #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.6.1

data/app/controllers/surveyor_controller.rb

@@ -0,0 +1,117 @@
+# The Surveyor controller a user taking a survey. It is semi-RESTful since it does not have a concrete representation model.
+# The "resource" is a survey attempt/session populating a response set.
+
+class SurveyorController < ApplicationController
+  
+  # Layout
+  layout Surveyor::Config['default.layout'] || 'surveyor_default'
+  
+  # Extending surveyor
+  include SurveyorControllerExtensions if Surveyor::Config['extend_controller'] && defined? SurveyorControllerExtensions
+  before_filter :extend_actions
+  
+  # RESTful authentication
+  if Surveyor::Config['use_restful_authentication']
+    include AuthenticatedSystem
+    before_filter :login_required
+  end
+  
+  # Get the response set or current_user
+  # before_filter :get_response_set, :except => [:new, :create]
+  before_filter :get_current_user, :only => [:new, :create]
+  
+  # Actions
+  def new
+    @surveys = Survey.find(:all)
+  end
+  def create
+    if (@survey = Survey.find_by_access_code(params[:survey_code])) && (@response_set = ResponseSet.create(:survey => @survey, :user_id => @current_user))
+      flash[:notice] = "Survey was successfully started."
+      redirect_to(edit_my_survey_path(:survey_code => @survey.access_code, :response_set_code  => @response_set.access_code))
+    else
+      flash[:notice] = "Unable to find that survey"
+      redirect_to(available_surveys_path)
+    end
+  end
+  def show
+  end
+  def edit
+    if @response_set = ResponseSet.find_by_access_code(params[:response_set_code], :include => {:responses => [:question, :answer]})
+      @survey = Survey.with_sections.find_by_id(@response_set.survey_id)
+      @sections = @survey.sections
+      @section = params[:section] ? @sections.with_includes.find(section_id_from(params[:section])) || @sections.with_includes.first : @sections.with_includes.first
+    else
+      flash[:notice] = "Unable to find your responses to the survey"
+      redirect_to(available_surveys_path)
+    end
+    
+    @dependents = (@response_set.unanswered_dependencies - @section.questions) || []
+  end
+  def update
+    if @response_set = ResponseSet.find_by_access_code(params[:response_set_code], :include => {:responses => :answer})
+      @response_set.current_section_id = params[:current_section_id]
+    else
+      flash[:notice] = "Unable to find your responses to the survey"
+      redirect_to(available_surveys_path)
+    end
+    
+    if params[:responses] or params[:response_groups]
+      @response_set.clear_responses
+      saved = @response_set.update_attributes(:response_attributes => (params[:responses] || {}).dup , :response_group_attributes => (params[:response_groups] || {}).dup) #copy (dup) to preserve params because we manipulate params in the response_set methods
+      if (saved && params[:finish])
+        @response_set.complete!
+        saved = @response_set.save!
+      end
+    end
+    respond_to do |format|
+      format.html do
+        if saved && params[:finish]
+          flash[:notice] = "Completed survey"
+          redirect_to surveyor_default_finish
+        else
+          flash[:notice] = "Unable to update survey" if !saved and !saved.nil? # saved.nil? is true if there are no questions on the page (i.e. if it only contains a label)
+          redirect_to :action => "edit", :anchor => anchor_from(params[:section]), :params => {:section => section_id_from(params[:section])}
+        end
+      end
+      # No redirect needed if we're talking to the page via json
+      format.js do
+        render :json => @response_set.all_dependencies.to_json
+      end
+    end
+  end
+
+  private
+  
+  # Filters
+  def get_current_user
+    @current_user = self.respond_to?(:current_user) ? self.current_user : nil
+  end
+  
+  # Params: the name of some submit buttons store the section we'd like to go to. for repeater questions, an anchor to the repeater group is also stored
+  # e.g. params[:section] = {"1"=>{"question_group_1"=>"<= add row"}}
+  def section_id_from(p)
+    p.respond_to?(:keys) ? p.keys.first : p
+  end
+  def anchor_from(p)
+    p.respond_to?(:keys) && p[p.keys.first].respond_to?(:keys) ? p[p.keys.first].keys.first : nil
+  end
+  
+  # Extending surveyor
+  def surveyor_default_finish
+    # http://www.postal-code.com/mrhappy/blog/2007/02/01/ruby-comparing-an-objects-class-in-a-case-statement/
+    # http://www.skorks.com/2009/08/how-a-ruby-case-statement-works-and-what-you-can-do-with-it/
+    case finish = Surveyor::Config['default.finish']
+    when String
+      return finish
+    when Symbol
+      return self.send(finish)
+    else
+      return '/surveys'
+    end
+  end
+  def extend_actions
+    # http://blog.mattwynne.net/2009/07/11/rails-tip-use-polymorphism-to-extend-your-controllers-at-runtime/
+    self.extend SurveyorControllerExtensions::Actions if Surveyor::Config['extend_controller'] && defined? SurveyorControllerExtensions::Actions
+  end
+
+end

data/app/helpers/survey_form_builder.rb

@@ -0,0 +1,37 @@
+class SurveyFormBuilder < ActionView::Helpers::FormBuilder 
+  def survey_check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
+    fields = @template.survey_check_box(@object_name, method, options.merge(:object => @object), checked_value, unchecked_value)
+    fields[1]
+  end
+end
+
+module ActionView
+  module Helpers
+    module FormHelper
+      def survey_check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")
+        if (Rails::VERSION::STRING.to_f > 2.1)
+          InstanceTag.new(object_name, method, self, options.delete(:object)).to_survey_check_box_tag(options, checked_value, unchecked_value)
+        else
+          InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_survey_check_box_tag(options, checked_value, unchecked_value)
+        end
+      end
+    end
+
+    class InstanceTag
+      def to_survey_check_box_tag(options = {}, checked_value = "1", unchecked_value = "0")
+        options = options.stringify_keys
+        options["type"]     = "checkbox"
+        options["value"]    = checked_value
+        if options.has_key?("checked")
+          cv = options.delete "checked"
+          checked = cv == true || cv == "checked"
+        else
+          checked = self.class.check_box_checked?(value(object), checked_value)
+        end
+        options["checked"] = "checked" if checked
+        add_default_name_and_id(options)
+        [tag("input", "name" => options["name"], "type" => "hidden", "value" => unchecked_value), tag("input", options)]
+      end
+    end
+  end
+end

data/app/helpers/surveyor_helper.rb

@@ -0,0 +1,66 @@
+module SurveyorHelper
+  
+  # Configuration
+  def surveyor_config
+    Surveyor::Config
+  end
+  
+  # Layout: stylsheets and javascripts
+  def surveyor_includes
+    surveyor_stylsheets + surveyor_javascripts    
+  end
+  def surveyor_stylsheets
+    stylesheet_link_tag 'surveyor/reset', 'surveyor/surveyor', 'surveyor/ui.theme.css','surveyor/jquery-ui-slider-additions'
+  end
+  def surveyor_javascripts
+    javascript_include_tag 'surveyor/jquery-1.2.6.js', 'surveyor/jquery-ui-personalized-1.5.3.js', 'surveyor/accessibleUISlider.jQuery.js','surveyor/jquery.form.js', 'surveyor/surveyor.js'
+  end
+  
+  # Section: dependencies, menu, previous and next
+  def dependency_explanation_helper(question,response_set)
+    # Attempts to explain why this dependent question needs to be answered by referenced the dependent question and users response
+    trigger_responses = []
+    dependent_questions = Question.find_all_by_id(question.dependency.dependency_conditions.map(&:question_id)).uniq
+    response_set.responses.find_all_by_question_id(dependent_questions.map(&:id)).uniq.each do |resp|
+      trigger_responses << resp.to_s
+    end
+    "&nbsp;&nbsp;You answered &quot;#{trigger_responses.join("&quot; and &quot;")}&quot; to the question &quot;#{dependent_questions.map(&:text).join("&quot;,&quot;")}&quot;"
+  end
+  def menu_button_for(section)
+    submit_tag(section.title, :name => "section[#{section.id}]")
+  end
+  def previous_section
+    # submit_tag("&laquo; Previous section", :name => "section[#{@section.previous.id}]") unless @section.previous.nil?
+    # refactored to use copy in memory instead of making extra db calls
+    submit_tag("&laquo; Previous section", :name => "section[#{@sections[@sections.index(@section)-1].id}]") unless @sections.first == @section
+  end
+  def next_section
+    # @section.next.nil? ? submit_tag("Click here to finish", :name => "finish") : submit_tag("Next section &raquo;", :name => "section[#{@section.next.id}]")
+    # refactored to use copy in memory instead of making extra db calls
+    @sections.last == @section ? submit_tag("Click here to finish", :name => "finish") : submit_tag("Next section &raquo;", :name => "section[#{@sections[@sections.index(@section)+1].id}]")
+  end
+  
+  # Questions
+  def next_number
+    @n ||= 0
+    "#{@n += 1}<span style='padding-left:0.1em;'>)</span>"
+  end
+  def split_text(text = "") # Split text into with "|" delimiter - parts to go before/after input element
+    {:prefix => text.split("|")[0].blank? ? "&nbsp;" : text.split("|")[0], :postfix => text.split("|")[1] || "&nbsp;"}
+  end
+  def question_help_helper(question)
+    question.help_text.blank? ? "" : %Q(<span class="question-help">#{question.help_text}</span>)
+  end
+
+  # Answers
+  def fields_for_response(response, &block)
+    fields_for("responses[#{response.question_id}][#{response.answer_id}]", response, :builder => SurveyFormBuilder, &block)
+  end
+  def fields_for_repeater_response(response, response_group, &block) # Changes the response hash to accept response groups for repeater elements
+    fields_for("response_groups[#{response.question_id}][#{response_group}][#{response.answer_id}]", response, :builder => SurveyFormBuilder, &block)
+  end
+  def fields_for_radio(response, &block)
+    fields_for("responses[#{response.question_id}]", response, :builder => SurveyFormBuilder, &block)
+  end
+  
+end

data/app/models/answer.rb

@@ -0,0 +1,21 @@
+class Answer < ActiveRecord::Base
+  
+  # Associations
+  belongs_to :question
+  has_many :responses
+
+  # Scopes
+  default_scope :order => "display_order ASC"
+  
+  # Validations
+  validates_presence_of :text
+  validates_numericality_of :question_id, :allow_nil => false, :only_integer => true
+  #validates_uniqueness_of :reference_identifier
+  
+  # Methods
+  def renderer(q = question)  
+    r = [q.pick.to_s, self.response_class].compact.join("_")
+    r.blank? ? :default : r.to_sym
+  end
+  
+end

data/app/models/dependency.rb

@@ -0,0 +1,46 @@
+class Dependency < ActiveRecord::Base
+  # Associations
+  belongs_to :question
+  has_many :dependency_conditions
+  
+  # Scopes
+  named_scope :depending_on_questions, lambda {|question_ids| {:include => :dependency_conditions, :conditions => {:dependency_conditions => {:question_id => question_ids}} }}
+  
+  # Validations
+  validates_presence_of :rule
+  validates_format_of :rule, :with => /^(?:and|or|\)|\(|\d|\s)+$/ #TODO properly formed parenthesis etc.
+  validates_numericality_of :question_id
+
+  # Attribute aliases
+  alias_attribute :dependent_question_id, :question_id
+
+  # Is the method that determines if this dependency has been met within
+  # the provided response set
+  def met?(response_set)
+    if keyed_pairs = keyed_conditions(response_set)
+      return(rule_evaluation(keyed_pairs))
+    else
+      return(false)
+    end
+  end
+
+  # Pairs up the substitution key with the evaluated condition result for substitution into the rule
+  # Example: If you have two dependency conditions with rule keys "A" and "B" in the rule "A or B"
+  # calling keyed_condition_pairs will return {:A => true, :B => false}
+  def keyed_conditions(response_set)
+    keyed_pairs = {}
+    self.dependency_conditions.each do |dc|
+      keyed_pairs.merge!(dc.to_evaluation_hash(response_set))
+    end
+    return(keyed_pairs)
+  end
+
+  # Does the substiution and evaluation of the dependency rule with the keyed pairs
+  def rule_evaluation(keyed_pairs)
+    # subtitute into rule for evaluation
+    rgx = Regexp.new(self.dependency_conditions.map{|dc| dc.rule_key}.join("|")) # Making a regexp to only look for the keys used in the child conditions
+    #logger.debug("rexp: #{rgx.inspect} FOO: #{keyed_pairs.inspect} --- subbed rules: #{rule.gsub(rgx){|m| keyed_pairs[m.to_sym]}} --> #{eval(self.rule.gsub(rgx){|m| keyed_pairs[m.to_sym]})}")
+    eval(self.rule.gsub(rgx){|m| keyed_pairs[m.to_sym]}) # returns the evaluation of the rule and the conditions
+  end
+  
+end