Guide: Parsing and Data Model

TABLE OF CONTENTS

The DSL and parser

The Surveyor DSL allows you to write your questions and answers in nearly plain English.

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

    # 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

    # 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

    # ... other question, sections and such. See surveys/kitchen_sink_survey.rb for more.
 end

end

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.

The data model

Attributes common to Survey, SurveySection, QuestionGroup, Question, and Answer

• #reference_identifier: usually derived from paper numbering, reference_identifier can be assigned in the DSL e.g. question_1 or a_yes. The reference identifier is also used for dependencies and validations, and must be unique for questions within the scope of the survey1, and unique for answers within the scope of a question.
• #data_export_identifier: intended for data export
• #common_namespace: intended for mapping to a common vocabulary
• #common_identifier: intended for mapping to a common vocabulary
• #display_order: for sorting
• #custom_class: css class for this answer, for custom styling. Use with Survey#css_url, a path to your custom css stylesheet. not supported by nu_surveyor

Attributes common to QuestionGroup, Question, and Answer

• #custom_renderer: path to a custom view use to render the answer e.g. /partials/custom_answer. not supported by nu_surveyor
• #text: the text that the user sees.
• #help_text: intended to provide supporting explanation or examples when needed.

Recognized values

• QuestionGroup#display_type: default, inline, grid, repeater
• Question#display_type: default, label, inline, dropdown, slider, hidden, image
• Answer#response_class: answer, string, text, integer, float, date, datetime, time

NEXT: The JSON API and Exports