Home

The Surveyor Guide

1. Introduction
2. Parsing and Data Model
3. The JSON API and Exports
4. Special topics

Support

Start by reviewing the README.

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. 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.

Take a look at our screencast (a bit dated now).

Workflow

1. Design the survey
2. Parse survey bundle exec rake surveyor FILE=surveys/[your_survey_file.rb]
3. Users respond (usually via http://[your.server]/surveys)
4. Export the results

Some other helpful rake tasks:

• bundle exec rake surveyor:remove removes surveys that haven't been responded to.
• bundle exec rake surveyor:unparse exports a survey into a surveyor DSL file.

Question types

What surveyor does and doesn't do

Does do

• use a DSL to parse large surveys without hours of copy/paste into a gui builder
• support complex, rule-based dependencies (skip-logic)
• JSON export of both surveys and response sets
• allow customization of all models, views, and controller, as well as helpers and routes
• follow semantic versioning
• Exclusive checkboxes - a checkbox that when checked, unchecks all the others

Doesn't do

• Enforce mandatory questions (although it does have some1 methods2 on ResponseSet to support that)
• Dependencies within repeaters #235
• Validations within the UI #34, although it does have model support and database representations
• GUI creating, editing, deleting and administration of surveys #414
• Consistently support HTML tags in title, text, help_text attributes. We intend to move to markdown support #413 so that same survey definition can be used with nu_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.

NEXT: Parsing and Data Model