surveyor 1.2.0 → 1.3.0

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 History for Surveyor
 ====================
 
+1.3.0
+-----
+
+### Features
+
+- Upgrade to jQuery UI 1.10.0, jQuery 1.9.0, jQueryUI timepicker addons 1.2, and remove jQuery tools (#409)
+- Upgrade reset css
+- Added surveyor_translations table to support YAML-based localizations of surveys. (#420)
+- Add extension point for pre-JSON-export survey modifications (#416)
+- Add input mask for text entry fields (#415)
+
+### Fixes
+
+- Export null when datetime response has null datetime value
+- Move the help text to be after the answer text (#401)
+- Fix response serialization for date pick one answers (#400)
+- Remove ordering default scope on survey section methods (#417, #290)
+- Answers of labels should not be shown, within or without groups (#304)
+- Inline group questions should display inline (#303)
+- Evaluate all submitted questions for depdencies (#396)
+- Pick one answers with dates should display their dates correctly (#378)
+
+### Infrastructure
+
+- Added stacktests.sh shell script for testing different stacks
+
 1.2.0
 -----
 

data/README.md

@@ -1,240 +1,137 @@
-# Surveys On Rails
+## Why surveyor?
 
-Surveyor is a developer tool that brings surveys into Rails
-applications. Surveys are written in the Surveyor DSL (Domain Specific
-Language). Internally, Surveyor is a Rails engine distributed as a
-ruby gem, meaning it is straightforward to override or extend its
-behaviors in your Rails app without maintaining a fork.
+Surveyor is a developer tool to deliver surveys in Rails applications.
+Surveys are written in the surveyor DSL (Domain Specific
+Language). A DSL makes it significantly easier to import long surveys
+(one of the motivations for building surveyor was copy/paste fatigue).
+It enables non-programmers to write out, edit, and review surveys.
 
-## Why you might want to use Surveyor
+If your Rails app needs to asks users questions as part of a survey, quiz,
+or questionnaire then you should consider using surveyor. This gem was
+designed to deliver clinical research surveys to large populations,
+but it can be used for any type of survey.
 
-If your Rails app needs to asks users questions as part of a survey, quiz, or questionnaire then you should consider using Surveyor. This gem was designed to deliver clinical research surveys to large populations, but it can be used for any type of survey.
+Surveyor is a Rails engine distributed as a ruby gem, meaning it is
+straightforward to override or extend its behaviors in your Rails app
+without maintaining a fork.
 
-The Surveyor DSL defines questions, answers, question groups, survey sections, dependencies (e.g. if response to question 4 is A, then show question 5), and validations. Answers are the options available for each question - user input is called "responses" and are grouped into "response sets". A DSL makes it significantly easier to import long surveys (no more click/copy/paste). It also enables non-programmers to write out, edit, re-edit... any number of surveys.
+## Requirements
 
-## DSL example
-
-The Surveyor DSL supports a wide range of question types (too many to list here) and complex dependency logic. Here are the first few questions of the "kitchen sink" survey which should give you and idea of how it works. The full example with all the types of questions available if you follow the installation instructions below.
-
-    survey "Kitchen Sink survey" do
-
-      section "Basic questions" do
-        # A label is a question that accepts no answers
-        label "These questions are examples of the basic supported input types"
-
-        # A basic question with radio buttons
-        question_1 "What is your favorite color?", :pick => :one
-        answer "red"
-        answer "blue"
-        answer "green"
-        answer "yellow"
-        answer :other
+Surveyor works with:
 
-        # A basic question with checkboxes
-        # "question" and "answer" may be abbreviated as "q" and "a"
-        q_2 "Choose the colors you don't like", :pick => :any
-        a_1 "red"
-        a_2 "blue"
-        a_3 "green"
-        a_4 "yellow"
-        a :omit
+* Ruby 1.8.7, 1.9.2, and 1.9.3
+* Rails 3.0-3.2
 
-        # A dependent question, with conditions and rule to logically join them
-        # the question's reference identifier is "2a", and the answer's reference_identifier is "1"
-        # question reference identifiers used in conditions need to be unique on a survey for the lookups to work
-        q_2a "Please explain why you don't like this color?"
-        a_1 "explanation", :text
-        dependency :rule => "A or B or C or D"
-        condition_A :q_2, "==", :a_1
-        condition_B :q_2, "==", :a_2
-        condition_C :q_2, "==", :a_3
-        condition_D :q_2, "==", :a_4
+Some key dependencies are:
 
-        # ... other question, sections and such. See surveys/kitchen_sink_survey.rb for more.
-     end
+* HAML
+* Sass
+* Formtastic
 
-    end
+A more exhaustive list can be found in the [gemspec][].
 
-The first question is "pick one" (radio buttons) with "other". The second question is "pick any" (checkboxes) with the option to "omit". It also features a dependency with a follow up question. Notice the dependency rule is defined as a string. We support complex dependency such as "A and (B or C) and D" or "A or ((B and C) or D)". The conditions are evaluated separately using the operators "==","!=","<>", ">=","<" the substituted by letter into to the dependency rule and evaluated.
+[gemspec]: https://github.com/NUBIC/surveyor/blob/master/surveyor.gemspec
 
-# Installation
+## Install
 
 Add surveyor to your Gemfile:
 
     gem "surveyor"
 
-Then run:
+Bundle, install, and migrate:
 
     bundle install
-
-Generate assets, run migrations:
-
     script/rails generate surveyor:install
     bundle exec rake db:migrate
 
-Try out the "kitchen sink" survey. The rake task above generates surveys from our custom survey DSL (a good format for end users and stakeholders).
+Parse the "kitchen sink" survey ([kitchen sink](http://en.wiktionary.org/wiki/everything_but_the_kitchen_sink) means almost everything)
 
     bundle exec rake surveyor FILE=surveys/kitchen_sink_survey.rb
 
-Start up your app and visit http://localhost:3000/surveys
-
-Try taking the survey and compare it to the contents of the DSL file kitchen\_sink\_survey.rb. See how the DSL maps to what you see.
+Start up your app, visit `/surveys`, compare what you see to [kitchen\_sink\_survey.rb][kitchensink] and try responding to the survey.
 
-There are two other useful rake tasks:
+[kitchensink]: http://github.com/NUBIC/surveyor/blob/master/lib/generators/surveyor/templates/surveys/kitchen_sink_survey.rb
 
-* `surveyor:remove` removes all unused surveys.
-* `rake surveyor:unparse` exports a survey from the application into a
-  file in the surveyor DSL.
+## Customize surveyor
 
-# Upgrading
+Surveyor's controller, helper, models, and views may be overridden by classes in your `app` folder. To generate a sample custom controller and layout run:
 
-When you are ready to update to the latest version of Surveyor, just do
+    script/rails generate surveyor:custom
 
-    bundle update surveyor
+and read `surveys/EXTENDING\_SURVEYOR`
 
-and you'll get the latest version that bundler thinks you can use based on the
-constraints in your Gemfile.
+## Upgrade
 
-After you've installed a new version, you should always re-run the surveyor
-generator:
+To get the latest version of surveyor, bundle, install and migrate:
 
+    bundle update surveyor
     script/rails generate surveyor:install
+    bundle exec rake db:migrate
 
-This will copy over any new or updated assets and new migrations. Use your VCS'
-utilities to review what's changed, then commit the new versions.
+and review the [changelog][] for changes that may affect your customizations.
 
-    git status
-    git diff
-    [...]
-    git add -A
-    git commit
+[changelog]: https://github.com/NUBIC/surveyor/blob/master/CHANGELOG.md
 
-If there were new migrations, you'll want to be sure to run them before the next
-time you start your app:
+## Users of spork
 
-    bundle exec rake db:migrate
+There is [an issue with spork and custom inputs in formatstic (#851)][851]. A workaround (thanks rmm5t!):
 
-Finally, review the [changelog][] entries corresponding to the versions between
-your original version and the version you've updated to. There may be changes
-which will affect your customizations. There should be hints in the changelog
-or the referenced issues for what to update when necessary.
+    Spork.prefork do
+      # ...
+      surveyor_path = Gem.loaded_specs['surveyor'].full_gem_path
+      Dir["#{surveyor_path}/app/inputs/*_input.rb"].each { |f| require File.basename(f) }
+      # ...
+    end
 
-[changelog]: https://github.com/NUBIC/surveyor/blob/master/CHANGELOG.md
+[851]: https://github.com/justinfrench/formtastic/issues/851
 
-## Following master
+## Follow master
 
-If you are following along with pre-release versions of Surveyor using a `:git`
+If you are following pre-release versions of surveyor using a `:git`
 source in your Gemfile, be particularly careful about reviewing migrations after
-updating Surveyor and re-running the generator. We will never change a migration
-between two released versions of Surveyor. However, we may on rare occasions
+updating surveyor and re-running the generator. We will never change a migration
+between two released versions of surveyor. However, we may on rare occasions
 change a migration which has been merged into master. When this happens, you'll
 need to assess the differences and decide on an appropriate course of action for
-your app.
-
-If you aren't sure what this means, we do not recommend that you deploy an app
+your app. If you aren't sure what this means, we do not recommend that you deploy an app
 that's locked to surveyor master into production.
 
-# Customizing surveyor
-
-Surveyor's controller, models, and views may be customized via classes in your app/models, app/helpers and app/controllers directories. To generate a sample custom controller and layout, run:
-
-    script/rails generate surveyor:custom
-
-and read surveys/EXTENDING\_SURVEYOR
-
-# The asset pipeline
-
-Surveyor is now aware of the Rails asset pipeline (http://guides.rubyonrails.org/asset_pipeline.html). With the asset pipeline enabled `Rails.application.config.assets.enabled == true`, then the `surveyor:install` generator will generate `app/assets/stylesheets/surveyor_all.css` and `app/assets/javascripts/surveyor_all.js` manifest files and link them from the surveyor\_default layout.  Assets remain in the gem and are picked up for inclusion and pre-compilation from there if `config/environments/production.rb` is set to include surveyor assets.
-
-    # Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
-    config.assets.precompile += %w( surveyor_all.js surveyor_all.css )
-
-The previous copy-to-application behavior still exists in the case where the asset pipeline is missing or disabled.
-
-# PDF support
-
-* Add the following lines to your Gemfile:
-
-<pre>
-	gem 'pdfkit'
-	gem 'wkhtmltopdf'
-</pre>
-
-or on OSX:
-
-<pre>
-	gem 'pdfkit'
-	gem 'wkhtmltopdf-binary'
-</pre>
-
-* Add the following to your application.rb:
-
-<pre>
-	config.middleware.use PDFKit::Middleware
-</pre>
-
-* Create links with :format => 'pdf' in them, for example:
-
-<pre>
-	%li= link_to "PDF", view_my_survey_path(:survey_code => response_set.survey.access_code, :response_set_code => response_set.access_code, :format => 'pdf')
-</pre>
-
-# Requirements
-
-Surveyor works with:
-
-* Ruby 1.8.7, 1.9.2, and 1.9.3
-* Rails 3.0-3.2
-
-Some key library dependencies are:
-
-* HAML
-* Sass
-* Formtastic
-
-A more exhaustive list can be found in the gemspec.
-
-# Support
+## Support
 
 For general discussion (e.g., "how do I do this?"), please send a message to the
 [surveyor-dev][] group. This group is moderated to keep out spam; don't be
 surprised if your message isn't posted immediately.
 
-For reproducible bugs, please file an issue on the [GitHub issue
-tracker][issues]. Please include a minimal test case (a detailed description of
+For reproducible bugs, please file an issue on the [GitHub issue tracker][issues].
+Please include a minimal test case (a detailed description of
 how to trigger the bug in a clean rails application). If you aren't sure how to
 isolate the bug, send a message to [surveyor-dev][] with what you know and we'll
 try to help.
 
+For build status see our [continuous integration page][ci].
+
+Take a look at our [screencast][] (a bit dated now).
+
 [surveyor-dev]: https://groups.google.com/group/surveyor-dev
 [issues]: https://github.com/NUBIC/surveyor/issues
+[ci]:https://public-ci.nubic.northwestern.edu/job/surveyor/
+[screencast]:http://vimeo.com/7051279
 
-# Contributing, testing
+## Contribute, test
 
 To work on the code, fork this github project. Install [bundler][] if
-you don't have it, then run
+you don't have it, then bundle, generate the app in `testbed`, and run the specs and features
 
     $ bundle update
-
-to install all the necessary gems. Then
-
     $ bundle exec rake testbed
-
-to generate a test app in `testbed`. Now you can run
-
     $ bundle exec rake spec
-
-to run the specs and
-
     $ bundle exec rake cucumber
 
-to run the features and start writing tests!
-
 [bundler]: http://gembundler.com/
 
 ## Selenium
 
-Some of Surveyor's integration tests use Selenium WebDriver and Capybara. The
+Some of surveyor's integration tests use Selenium WebDriver and Capybara. The
 WebDriver-based tests default to running in Chrome due to an unfortunate
 [Firefox bug][FF566671]. For them to run, you'll either need:
 
@@ -253,4 +150,6 @@ Firefox to retain focus, otherwise some tests will fail.
 [FF566671]: https://bugzilla.mozilla.org/show_bug.cgi?id=566671
 [chromedriver]: http://code.google.com/p/selenium/wiki/ChromeDriver
 
-Copyright (c) 2008-2011 Brian Chamberlain and Mark Yoon, released under the MIT license
+Copyright (c) 2008-2013 Brian Chamberlain and Mark Yoon, released under the [MIT license][mit]
+
+[mit]: https://github.com/NUBIC/surveyor/blob/master/MIT-LICENSE

data/app/models/survey_translation.rb

@@ -0,0 +1,5 @@
+class SurveyTranslation < ActiveRecord::Base
+  unloadable
+  include Surveyor::Models::SurveyTranslationMethods
+end
+

data/app/views/partials/_answer.html.haml

@@ -4,18 +4,22 @@
 - i = response_idx(q.pick != "one") # argument will be false (don't increment i) if we're on radio buttons
 - disabled = defined?(disableFlag) ? disableFlag : false
 = f.semantic_fields_for i, r do |ff|
-  %span.help= render_help_text(a, @render_context) unless g && g.display_type == "grid"
   = ff.input :question_id, :as => :quiet unless q.pick == "one" # don't repeat question_id if we're on radio buttons
   = ff.input :api_id, :as => :quiet unless q.pick == "one"
   = ff.input :response_group, :value => rg, :as => :quiet if q.pick != "one" && g && g.display_type == "repeater"
   - case q.pick
   - when "one"
-    = ff.input :answer_id, :as => :surveyor_radio, :collection => [[a_text(a, nil, @render_context), a.id]], :label => false, :input_html => {:class => a.css_class, :disabled => disabled}, :response_class => a.response_class
+    = ff.input :answer_id, :as => :surveyor_radio, :collection => [[a.text_for(nil, @render_context, I18n.locale), a.id]], :label => false, :input_html => {:class => a.css_class, :disabled => disabled}, :response_class => a.response_class
   - when "any"
-    = ff.input :answer_id, :as => :surveyor_check_boxes, :collection => [[a_text(a, nil, @render_context), a.id]], :label => false, :input_html => {:class => a.css_class, :disabled => disabled}, :response_class => a.response_class
+    = ff.input :answer_id, :as => :surveyor_check_boxes, :collection => [[a.text_for(nil, @render_context, I18n.locale), a.id]], :label => false, :input_html => {:class => a.css_class, :disabled => disabled}, :response_class => a.response_class
   - when "none"
     - if %w(date datetime time float integer string text).include? a.response_class
       = ff.input :answer_id, :as => :quiet, :input_html => {:class => a.css_class, :value => a.id}
-      = ff.input rc_to_attr(a.response_class), :as => rc_to_as(a.response_class), :label => a_text(a, :pre, @render_context).blank? ? false : a_text(a, :pre, @render_context), :hint => a_text(a, :post, @render_context), :input_html => generate_pick_none_input_html(r.as(a.response_class), a.default_value, a.css_class, a.response_class, disabled)
+      = ff.input rc_to_attr(a.response_class),
+                  :as         => rc_to_as(a.response_class),
+                  :label      => a.text_for(:pre, @render_context, I18n.locale).blank? ? false : a.text_for(:pre, @render_context, I18n.locale),
+                  :hint       => a.text_for(:post, @render_context, I18n.locale),
+                  :input_html => generate_pick_none_input_html(r.as(a.response_class), a.default_value_for(@render_context, I18n.locale), a.css_class, a.response_class, disabled, a.input_mask, a.input_mask_placeholder)
     - else
-      = a_text(a, nil, @render_context)
+      = a.text_for(nil, @render_context, I18n.locale)
+  %span.help= a.help_text_for(@render_context, I18n.locale) unless g && g.display_type == "grid"

data/app/views/partials/_question.html.haml

@@ -3,10 +3,10 @@
 - renderer = q.renderer(g ||= nil)
 - disabled = defined?(disableFlag) ? disableFlag : false
 - unless q.display_type == "hidden"
-  = f.inputs q_text(q, @render_context), :id => rg ? "q_#{q.id}_#{rg}" : "q_#{q.id}", :class => "q_#{renderer} #{q.css_class(@response_set)}" do
-    %span.help= render_help_text(q, @render_context)
+  = f.inputs q_text(q, @render_context, I18n.locale), :id => rg ? "q_#{q.id}_#{rg}" : "q_#{q.id}", :class => "q_#{renderer} #{q.css_class(@response_set)}" do
+    %span.help= q.help_text_for(@render_context, I18n.locale)
     - case renderer
-    - when :image, :label
+    - when  :image, :label, :default_label, :inline_label, :repeater_label
     - when :dropdown, :inline_dropdown, :default_dropdown, :slider, :repeater_dropdown
       - r = response_for(@response_set, q, nil, rg)
       - i = response_idx

data/app/views/partials/_question_group.html.haml

@@ -1,7 +1,7 @@
 - renderer = g.renderer
 - unless g.display_type == "hidden"
-  = f.inputs q_text(g, @render_context), :id => "g_#{g.id}", :class => "g_#{renderer} #{g.css_class(@response_set)}" do
-    %li.help= render_help_text(g, @render_context)
+  = f.inputs "#{next_question_number(g)}#{g.text_for(@render_context, I18n.locale)}", :id => "g_#{g.id}", :class => "g_#{renderer} #{g.css_class(@response_set)}" do
+    %li.help= g.help_text_for(@render_context, I18n.locale)
     - case renderer
       - when :grid
         %li
@@ -16,22 +16,23 @@
                   %th  
                   - ten_questions.first.answers.each do |a|
                     %th
-                      =a_text(a)
-                      %span.help= render_help_text(a, @render_context)
+                      = a.text_for(nil, @render_context, I18n.locale)
+                      %span.help= a.help_text_for(@render_context, I18n.locale)
                   %th  
                 - ten_questions.each_with_index do |q, i|
                   %tr{:id => "q_#{q.id}", :class => "q_#{renderer} #{q.css_class(@response_set)}"}
                     %th
-                      = q.split_text(:pre)
+                      = q.text_for(:pre, @render_context, I18n.locale)
+                      = q.help_text_for(@render_context, I18n.locale)
                       - if q.pick == "one"
                         - r = response_for(@response_set, q, nil, g)
                         - i = response_idx  # increment the response index since the answer partial skips for q.pick == one
                         = f.semantic_fields_for i, r do |ff|
                           = ff.input :question_id, :as => :quiet
                           = ff.input :api_id, :as => :quiet
-                    - q.answers.each do |a|
-                      %td= render a.custom_renderer || '/partials/answer', :g => g, :q => q, :a => a, :f => f
-                    %th= q.split_text(:post)
+                      - q.answers.each do |a|
+                        %td= render(a.custom_renderer || '/partials/answer', :g => g, :q => q, :a => a, :f => f) unless q.display_type == "label"
+                      %th= q.text_for(:post, @render_context, I18n.locale)
       - when :repeater
         - (@response_set.count_group_responses(qs) + 1).times do |rg|
           %li

data/app/views/partials/_section.html.haml

@@ -1,5 +1,5 @@
 = div_for @section, :class => @section.custom_class do
-  %span.title= @section.title
+  %span.title= @section.translation(I18n.locale)[:title]
   - qs ||= []
   - (questions = @section.questions).each_with_index do |q, i|
     - if q.part_of_group?

data/app/views/surveyor/edit.html.haml

@@ -4,11 +4,11 @@
       = flash_messages(types)
       .close
   = semantic_form_for(@response_set, :as => :r, :url => update_my_survey_path, :html => {:method => :put, :id => "survey_form", :class => @survey.custom_class}) do |f|
-  
+
     = hidden_field_tag :surveyor_javascript_enabled, false
-  
+
     = render 'partials/section_menu' # unless @sections.size < 3
-    .survey_title= @survey.title
+    .survey_title= @survey.translation(I18n.locale)[:title]
     .previous_section= previous_section
     = render 'partials/dependents' unless @dependents.empty?
     - if false #@response_set.no_responses_for_section?(@section) # cache if response_set has no responses for current section