Constructing basic surveys

CitrusBuilder offers two different modes of survey building. Both modes of construction are suitable for different use cases. To create simple surveys the survey structure can be created at once by using the do ... end syntax. All survey components that have child elements, e.g. survey, question_group or multiple_short_text_question, do allow for this method of construction.

Let's imagine we want to create a simple survey for an introductory statistics class where we want to gather data on the age (in years), gender, and height (in cm) of the students.

In order to accomplish this, we need to construct a survey with

1. A gender_select,
2. A numerical_input for the participants age,
3. A numerical_input for the participants height

using CitrusBuilder

my_statistics_survey = survey(100000, "Statistics 101 survey") do
    question_group(1, "") do  # this is a dummy question group, no title needed
        gender_select("gender", "Please select your gender."),
        numerical_input("age", "Please state your age in years.", minimum=18, integer_only=true),
        numerical_input("height", "Please state your height in centimeters.", minimum=0, maximum=250, integer_only=true)
    end
end

Survey with 1 group and 3 questions.
Statistics 101 survey (id: 100000)
└──  (id: 1)
    ├── Please select your gender. (id: gender)
    ├── Please state your age in years. (id: age)
    └── Please state your height in centimeters. (id: height)

For the numerical_input questions we also imposed several restrictions provided by LimeSurvey:

1. age must be at least 18 and can only have integer values,
2. height must be a non-negative integer with a maximum height of 250cm.

Now that the survey is complete, it can be exported to an .lss file.

write("statistics_101.lss", my_statistics_survey)

Alternative approach

An alternative to the basic survey construction outlined in the previous section is to build the survey iteratively. CitrusBuilder overloads the Julia Base functions append!, insert!, and prepend!. These functions can be used to append, insert or prepend survey components to a survey respectively. A simple example of this method was given in the Getting Started section.

Consider again the example from the previous section: A survey gathering data on the age, gender, and height of the survey participants. Using this approach we first must construct an empty survey,

using CitrusBuilder

my_statistics_survey = survey(100000, "Statistics 101 survey")

Survey with 0 groups and 0 questions.
Statistics 101 survey (id: 100000)

Now we can define and append the required question group to the survey,

g1 = question_group(1, "")
append!(my_statistics_survey, g1)

my_statistics_survey

Survey with 1 group and 0 questions.
Statistics 101 survey (id: 100000)
└──  (id: 1)

Questions can then be appended to the question group g1.

append!(g1, gender_select("gender", "Please select your gender."))
append!(g1, numerical_input("age", "Please state your age in years.", minimum=18, integer_only=true))
append!(g1, numerical_input("height", "Please state your height in centimeters.", minimum=0, maximum=250, integer_only=true))

my_statistics_survey

Survey with 1 group and 3 questions.
Statistics 101 survey (id: 100000)
└──  (id: 1)
    ├── Please select your gender. (id: gender)
    ├── Please state your age in years. (id: age)
    └── Please state your height in centimeters. (id: height)

Again, we can export the survey to an .lss file using write.

write("statistics_101.lss", my_statistics_survey)