Functions

append!(component::AbstractSurveyComponent, item)

Insert one or multiple items to the end of component's children. Returns the appended item.

Examples

julia> s = survey(100000, "my survey")
julia> append!(s, question_group(1, "a question group"))

julia> s = survey(100000, "my survey")
julia> append!(s, [
    question_group(1, "first question group"),
    question_group(2, "second question group")
])

insert!(component::AbstractSurveyComponent, index::Integer, item)

Insert one or multiple items into component's children at the given index. Returns the appended item.

Examples

julia> s = survey(100000, "my survey") do
    question_group(1, "first question group"),
    question_group(2, "second question group")
end
julia> insert!(s, 2, question_group(3, "between first and second question group"))
julia> s
Survey with 3 groups and 0 questions.
my survey (id: 100000)
├── first question group (id: 1)
├── between first and second question group (id: 3)
└── second question group (id: 2)

prepend!(component::AbstractSurveyComponent, item)

Insert one or multiple items to the beginning of component's children. Returns the prepended item.

Examples

julia> s = survey(100000, "my survey")
julia> prepend!(s, question_group(1, "first question group"))

julia> g = question_group(1, "a question group")
julia> qs = [
    gender_select("q1", "A gender select"),
    short_text_question("q2", "Please state your full name.")
]
julia> prepend!(g, qs)

survey(id, title::String; children, settings)

Construct a single-language Survey. children is an optional keyword argument and can be omitted.

Examples

Survey without children

julia> s = survey(100000, "my survey")
Survey with 0 groups and 0 questions.
my survey (id: 100000)

survey with children

julia> s = survey(100000, "my survey", children = [
    question_group(1, "first question group"),
    question_group(2, "second question group")
])
Survey with 2 groups and 0 questions.
my survey (id: 100000)
├── first question group (id: 1)
└── second question group (id: 2)

survey(children::Function, id, title::String; settings)

Construct a single-language Survey using do ... end syntax.

Examples

julia> s = survey(100000, "my survey") do
    question_group(1, "first question group"),
    question_group(2, "second question group")
end
Survey with 2 groups and 0 questions.
my survey (id: 100000)
├── first question group (id: 1)
└── second question group (id: 2)

survey(id, language_settings::LanguageSettings; children, settings)

Construct a multi-language Survey. children is an optional keyword argument and can be omitted.

Examples

Survey without children

julia> s = survey(100000, language_settings([
    language_setting("en", "A multi-language survey"),
    language_setting("de", "Eine mehrsprachige Umfrage")
]))
Survey with 0 groups and 0 questions.
A multi-language survey (id: 100000)

Survey with children

julia> s = survey(100000, language_settings([
    language_setting("en", "A multi-language survey"),
    language_setting("de", "Eine mehrsprachige Umfrage")
]), children = [question_group(1, language_settings([
    language_setting("en", "first question group"),
    language_setting("de", "Erste Fragengruppe")
]))])
Survey with 1 group and 0 questions.
A multi-language survey (id: 100000)
└── first question group (id: 1)

survey(children::Function, id, language_settings::LanguageSettings; settings)

Construct a multi-language Survey using do ... end syntax.

Examples

julia> s = survey(100000, language_settings([
    language_setting("en", "A multi-language survey"),
    language_setting("de", "Eine mehrsprachige Umfrage")
])) do
    question_group(1, language_settings([
        language_setting("en", "first question group"),
        language_setting("de", "Erste Fragengruppe")
    ]))
end
Survey with 1 group and 0 questions.
A multi-language survey (id: 100000)
└── first question group (id: 1)

question_group(id, title::String; description, children)

Construct a single-language question group. Both description and children are optional keyword arguments that can be omitted.

Examples

julia> g = question_group(1, "a question group")

julia> g = question_group(1, "a question group"; description="A simple description")

julia> questions = [short_text_question("q$i", "question $i") for i in 1:3]
julia> g = question_group(1, "a question group"; children=questions)

question_group(children::Function, id, title::String; description)

Construct a single-language question group using do...end syntax. description is an optional keyword argument that can be omitted.

Examples

julia> g = question_group(1, "a question group") do
    short_text_question("q1", "first question")
end

question_group(id, language_settings::LanguageSettings; children)

Construct a multi-language question group. children is an optional keywird argument that can be omitted.

Examples

julia> g = question_group(1, language_settings([
    language_setting("de", "Eine Fragengruppe"),
    language_setting("en", "A question group")
]))

question_group(children::Function, id, language_settings::LanguageSettings)

Construct a multi-language question group using do...end syntax.

Examples

julia> g = question_group(1, language_settings([
    language_setting("de", "Eine Fragengruppe"),
    language_setting("en", "A question group")
])) do
    short_text_question("q1", language_settings([
        language_setting("de", "Eine Frage")
        language_setting("en", "A question")
    ]))
end

short_text_question(id, language_settings::LanguageSettings; kwargs...)
short_text_question(id, title::String; help=nothing, default=nothing, kwargs...)

Construct a short text question. If the question is constructed using a title, the global default language is used by default.

For a list of available keyword arguments see Question.

Examples

Simple short text questions using a single language can be constructed using a title string.

julia> q = short_text_question("q1", "my question")

To construct a multi-language short text question, use language_settings.

julia> q = short_text_question("q2", language_settings([
    language_setting("en", "question title"),
    language_setting("de", "Fragetitel")
]))

long_text_question(id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language long text question.

For a list of available keyword arguments see Question.

long_text_question(id, title::String; help, default, kwargs...)

Construct a single-language long text question.

For a list of available keyword arguments see Question.

huge_text_question(id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language long text question.

For a list of available keyword arguments see Question.

huge_text_question(id, title::String; help, default, kwargs...)

Construct a single-language long text question.

For a list of available keyword arguments see Question.

multiple_short_text_question(id, language_settings::LanguageSettings; subquestions, kwargs...)

Construct a multi-language multiple short text question.

For a list of available keyword arguments see Question.

multiple_short_text_question(id, title::String; subquestions, help, kwargs...)

Construct a single-language multiple short text question.

For a list of available keyword arguments see Question.

multiple_short_text_question(children::Function, id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language multiple short text question using do...end syntax.

For a list of available keyword arguments see Question.

multiple_short_text_question(children::Function, id, title::String; help, kwargs...)

Construct a single-language multiple short text question using do...end syntax.

For a list of available keyword arguments see Question.

five_point_choice_question(id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language five point choice question.

For a list of available keyword arguments see Question.

five_point_choice_question(id, title::String; help=nothing, kwargs...)

Construct a single-language five point choice question.

For a list of available keyword arguments see Question.

dropdown_list_question(id, language_settings::LanguageSettings, options::ResponseScale; kwargs...)

Construct a multi-language dropdown list question.

For a list of available keyword arguments see Question.

dropdown_list_question(id, title::String, optins::ResponseScale; help=nothing, kwargs...)

Construct a single-language dropdown list question.

For a list of available keyword arguments see Question.

radio_list_question(id, language_settings::LanguageSettings, options::ResponseScale; comment=false, kwargs...)

Construct a multi-language radio list question.

For a list of additional keyword arguments see Question.

radio_list_question(id, title::String, options::ResponseScale; help=nothing, kwargs...)

Construct a single-language radio list question.

For a list of additional keyword arguments see Question.

multiple_choice_question(id, language_settings::LanguageSettings; subquestions, comments=false, kwargs...)

Construct a multi-language multiple choice question.

For a list of additional keyword arguments see Question.

multiple_choice_question(id, title::String; subquestions, help=nothing, kwargs...)

Construct a single-language multiple choice question.

For a list of additional keyword arguments see Question.

multiple_choice_question(children::Function, id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language multiple choice question using do...end syntax.

For a list of additional keyword arguments see Question.

multiple_choice_question(children::Function, id, title::String; kwargs...)

Construct a single-language multiple choice question using do...end syntax.

For a list of additional keyword arguments see Question.

array_five_point_choice_question(id, language_settings::LanguageSettings; subquestions, kwargs...)
array_five_point_choice_question(id, title::String; subquestions, help=nothing, kwargs...)
array_five_point_choice_question(children::Function, id, language_settings::LanguageSettings; kwargs...)
array_five_point_choice_question(children::Function, id, title::String; kwargs...)

Construct an array five point choice question.

For a list of additional keyword arguments see Question.

array_ten_point_choice_question(id, language_settings::LanguageSettings; subquestions, kwargs...)
array_ten_point_choice_question(id, title::String; subquestions, help=nothing, kwargs...)
array_ten_point_choice_question(children::Function, id, language_settings::LanguageSettings; kwargs...)
array_ten_point_choice_question(children::Function, id, title::String; kwargs...)

Construct an array ten point choice question.

For a list of additional keyword arguments see Question.

array_yes_no_question(id, language_settings::LanguageSettings; subquestions, kwargs...)
array_yes_no_question(id, title::String; subquestions, help=nothing, kwargs...)
array_yes_no_question(children::Function, id, language_settings::LanguageSettings; kwargs...)
array_yes_no_question(children::Function, id, title::String; kwargs...)

Construct an array yes/no question.

For a list of additional keyword arguments see Question.

array_increase_decrease_question(id, language_settings::LanguageSettings; subquestions, kwargs...)
array_increase_decrease_question(id, title::String; subquestions, help=nothing, kwargs...)
array_increase_decrease_question(children::Function, id, language_settings::LanguageSettings; kwargs...)
array_increase_decrease_question(children::Function, id, title::String; kwargs...)

Construct an array increase/decrease question.

For a list of additional keyword arguments see Question.

array_question(id, language_settings::LanguageSettings, options::VectorOrElemenet{ResponseScale}; subquestions, type="default", kwargs...)
array_question(id, title::String, options::VectorOrElement{ResponseScale}; help=nothing, kwargs...)
array_question(children::Function, id, language_settings::LanguageSettings, options; kwargs...)
array_question(children::Function, id, title::String, options; kwargs...)

Construct an array question.

Specify the question type to determine which kind of array question is to be constructed. If type="dual" then an array of 2 ResponseScale must be provided. Otherwise a single ResponseScale is required.

Available types

• "default": Array
• "text": Array (Texts)
• "dropdown": Array (Numbers)
• "dual": Array dual scale
• "bycolumn": Array by column

date_select(id, language_settings::LanguageSettings; minimum=nothing, maximum=nothing, kwargs...)
date_select(id, title::String; help=nothing, kwargs...)

Construct a date select question.

Keyword arguments

• minimum: The minimum allowed date
• maximum: The maximum allowed date

For a list of additional keyword arguments see Question.

file_upload(id, language_settings::LanguageSettings; kwargs...)
file_upload(id, title::String; help=nothing, kwargs...)

Construct a file upload question.

gender_select(id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language gender select.

gender_select(id, title::String; help=nothing, kwargs...)

Construct a single-language gender select.

language_switch(id, language_settings::LanguageSettings; kwargs...)

Construct a multi-language language switch.

language_switch(id, title::String; help=nothing, kwargs...)

Construct a single-language language switch.

numerical_input(id, language_settings::LanguageSettings; minimum=nothing, maximum=nothing, integer_only=false, kwargs...)
numerical_input(id, title::String; help=nothing, kwargs...)

Construct a multi-language numerical input.

Keyword arguments

• minimum: The minimum value
• maximum: The maximum value
• integer_only: Permit only integer values

multiple_numerical_input(id, language_settings::LanguageSettings; subquestions, kwargs...)
multiple_numerical_input(id, title::String; subquestions, help=nothing, kwargs...)
multiple_numerical_input(children::Function, id, language_settings::LanguageSettings; kwargs...)
multiple_numerical_input(children::Function, id, title::String; kwargs...)

Construct a multiple numerical input question.

ranking(id, language_settings::LanguageSettings, options::ResponseScale; kwargs...)
ranking(id, title::String, options::ResponseScale; help=nothing, kwargs...)

Construct a ranking question.

text_display(id, language_settings::LanguageSettings; kwargs...)
text_display(id, title::String; help=nothing, kwargs...)

Construct a text display question.

yes_no_question(id, language_settings::LanguageSettings; kwargs...)
yes_no_question(id, title::String; help=nothing, kwargs...)

Construct a yes/no question.

equation(id, language_settings::LanguageSettings; kwargs...)
equation(id, title::String; help=nothing, kwargs...)

Construct an equation question.

subquestion(; id, language_settings, relevance = "1")

Construct a multi-language subquestion.

subquestion(; id, title, relevance = "1")

Construct a subquestion using the default survey language.

language_settings(settings; same_default=false)
language_settings(language, title; same_default=false, kwargs...)

Construct LanguageSettings for a survey component. Settings for single can either be provided as settings::Vector{LanguageSetting} (see also language_setting) or a combination of language and title.

If multiple languages are provided and same_default=true then the default value of the default language is inherited by all other languages.

Examples

Simple construction of language settings for a single language:

language_settings("de", "Ein Titel")

If multiple languages are needed, construct settings using a vector of language_setting

language_settings([
    language_setting("en", "A title"),
    language_setting("de", "Ein Titel")
])

To inherit the default value of the default language, same_default can be used

language_settings([
    language_setting("en", "title", default="placeholder value"),
    language_setting("de", "Titel")
], same_default=true)

language_setting(language, title; kwargs...)

Construct a LanguageSetting for a survey component.

Arguments

• language: A language code. For a list of all available languages see https://translate.limesurvey.org/languages/
• title: The title of the survey component

Keyword arguments

• description: A description of the survey component
• help: A help text that is displayed for the survey component (questions only)
• default: The default value of the survey component (questions only)

Examples

language_setting("en", "title")
language_setting("en", "question title", help="some help for survey participants")

id(component::AbstractSurveyComponent)

Return the id of a survey component.

Examples

julia> q = short_text_question("q1", "title")
julia> id(q)
"q1"

title(component::AbstractSurveyComponent, language::String)

Return the title of the a survey component for a given language. If language is not provided the title for the default language of the component is returned.

Examples

julia> g = question_group(1, "my title")
julia> title(g)
"my title"

julia> g = question_group(1, language_settings([
    language_setting("en", "my title"),
    language_setting("de", "Mein Titel")
]))
julia> title(g, "en")
"my title"
julia> title(g, "de")
"Mein Titel"

help(component::AbstractSurveyComponent, language::String)

Return the help string of a survey component for a given language. If language is not provided the help for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", "my question", help="some help")
julia> help(q)
"some help"

has_description(component::AbstractSurveyComponent, language::String)

Returns whether or not the survey component has a description for a given language. If language is not provided the value for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", "title")
julia> has_description(q)
false

julia> q = short_text_question("q2", "title", description="some description")
julia> has_description(q)
true

description(component::AbstractSurveyComponent, language::String)

Returns the description of a survey component for a given language. If language is not provided the description for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", "title", description="answer this question")
julia> description(q)
"answer this question"

julia> q = short_text_question("q2", language_settings([
    language_setting("en", "some description"),
    language_setting("de", "Eine Beschreibung")
]))
julia> description(q)
"some description"

julia> description(q, "de")
"Eine Beschreibung"

languages(component::AbstractSurveyComponent)

Return a vector of languages of a survey component.

Examples

For components with a single language

julia> s = survey(100000, "survey title")
julia> languages(s)
["en"]

For multi-language components

julia> q = short_text_question("q1", language_settings([
    language_setting("en", "title"),
    language_setting("de", "Titel")
]))
julia> languages(q)
["en", "de"]

same_default(component::AbstractSurveyComponent)

Return if the survey component uses the same default value for all languages.

Examples

julia> q = short_text_question("q1", "title", default="some default value")
julia> same_default(q)
false

julia> q = short_text_question("q1", language_settings([
    language_setting("en", "title", default="some default value"),
    language_setting("de", "Titel")
], same_default=true))
julia> same_default(q)
true

has_help(component::AbstractSurveyComponent, language::String)

Return whether or not the survey component has a help string for a given language. If language is not provided the value for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", "title")
julia> has_help(q)
false

julia> q = short_text_question("q2", "title", help="some help")
julia> has_help(q)
true

default_language(component::AbstractSurveyComponent)

Return the default language of a survey component. The default language is defined as the first language of the component.

Examples

julia> g = question_group(1, "group title")
julia> default_language(g)
"en"

julia> default_language()
"en"
julia> g = question_group(1, language_settings([
    language_setting("de", "Gruppentitel"),
    language_settings("en", "group title")
]))
julia> default_language(g)
"de"

default_language()

Get the currently set default language (default: "en"). If no explicit language is provided when constructing Survey, QuestionGroup or Question the survey components will inherit the default language.

See also

To set the default language use set_default_language!

default(component::AbstractSurveyComponent, language::String)

Return the default value of a survey component. If language is provided the default value for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", language_settings([
    language_setting("en", "title", default="placeholder"),
    language_setting("de", "Titel", default="Platzhalter")
]))
julia> default(q)
"placeholder"
julia> default(q, "en")
"placeholder"
julia> default(q, "de")
"Platzhalter"

has_default(component::AbstractSurveyComponent, language::String)

Return whether or not a survey component has a default value for a given language. If language is not provided the default value for the default language of the component is returned.

Examples

julia> q = short_text_question("q1", "title")
julia> has_default(q)
false

julia> q = short_text_question("q2", "title", default="placeholder")
julia> has_default(q)
true

is_mandatory(question::Question)

Check if a Question is mandatory.

Examples

julia> q = short_text_question("q1", "A question")
julia> is_mandatory(q)
false

julia> q = short_text_question("q1", "A mandatory question", mandatory=true)
julia> is_mandatory(q)
true

has_other(question::Question)

Check if a Question has response option 'other'.

has_subquestions(question::Question)

Check if a Question has any subquestions.

Examples

julia> q = short_text_question("q1", "A question")
julia> has_subquestions(q)
false

julia> q = multiple_short_text_question("q1", "Multiple questions") do
    subquestion("sq1", "subquestion 1"),
    subquestion("sq2", "subquestion 2")
end
julia> has_subquestions(q)
true

has_response_options(questions::Question)

Check if a Question has any response options.

Examples

julia> q = five_point_choice_question("q1", "A question")
julia> has_response_options(q)
false

julia> options = response_scale([response_option("o1", "option 1")])
julia> q = dropdown_list_question("q1", "A dropdown question", options)
julia> has_response_options(q)
true

has_attributes(question::Question)

Check if a Question has any attributes.

Examples

julia> q = numerical_input("q1", "An input")
julia> has_attributes(q)
false

julia> q = numerical_input("q1", "An input with attributes", minimum=0, maximum=10)
julia> has_attributes(q)
true

attributes(question::Question)

Get the attributes of a Question.

Examples

julia> q = numerical_input("q1", "A numerical input", minimum=0, maximum=10)
julia> attributes(q)
Dict{String, Any} with 2 entries:
  "min_num_value_n" => 0
  "max_num_value_n" => 10

set_default_language!(lang::String)

Set DEFAULT_LANGUAGE of CitrusBuilder.

Examples

set_default_language!("de")
[ Info: Default language set to 'de'.

See also

To get the current value of DEFAULT_LANGUAGE see default_language.

write(filename::AbstractString, survey::Survey)

Write the XML structure of survey to a file. Make sure that the filename extension is .lss for the import in LimeSurvey.

Examples

julia> s = survey(100000, "my survey")
julia> write("mysurvey.lss", s)

xml(survey::Survey)

Construct an XML document from a Survey object.

Examples

julia> s = survey(100000, "my survey")
julia> xml(s)